Help Center

Menu

Modern UI util functions

Introduction

There are several helper functions that are available for use within Modern UI hook scripts and Freemarker templates.

Util functions

changeParam

Utility method used to change a query string parameter. Given a query string, a parameter name and a value it will either add the parameter if it doesn’t exist or replace its existing value with the new one. It takes three parameters:

  • qs: query string

  • paramName: name of the parameter to be changed

  • value: the new value of the parameter to be set

${changeParam(qs, paramName, value)}
html

Examples

Display a "More" link which is used to display more results in the type cluster in contextual navigation.

<li><a rel="more" href="${changeParam(s.category.moreLink, "type_max_clusters", "40")}" class="btn btn-link btn-sm"><small class="glyphicon glyphicon-plus"></small> More&hellip;</a></li>
html

computeQueryStringSignature

Computes a signature for a query string which is independent of the way parameters are encoded, or from their order. It takes one parameter:

  • qs: query string

${computeQueryStringSignature(qs)}

Examples

Build a list of previously visited queries (search history).

<#assign qsSignature = computeQueryStringSignature(QueryString) />
<#if session.searchHistory?? && (session.searchHistory?size gt 1 || session.searchHistory[0].searchParamsSignature != qsSignature)>
  ...
</#if>
html

facetScopeRemove

Utility method used in faceted navigation when building facets breadcrumbs. Used to remove a given list of facet constraints from the facetScope parameter of the query string. It takes two arguments:

  • qs: query string

  • paramNames: list of names of the facet constraint parameters to remove

${facetScopeRemove(qs, paramNames)}
html

Freemarker macro

The following macro can also be used to call this function:

<#macro FacetScopeRemove params=[]>
  <#compress>
  <#local qs><#nested></#local>
  ${facetScopeRemove(qs, params)}
  </#compress>
</#macro>
html

Examples

Remove the f.Location|X facet constraint from the facetScope parameter.

<a href="${question.collection.configuration.value("ui.modern.search_link")!}?<@FacetScopeRemove params=['f.Location|X']>${QueryString}</@FacetScopeRemove>"></a>
html

filesize

Formats a file size to be displayed in kilobytes (KB). It takes one parameter:

  • value: file size

${filesize(value)}
html

Examples

Display extension and size of the file.

<#if s.result.fileType!?matches("(doc|docx|ppt|pptx|rtf|xls|xlsx|xlsm|pdf)", "r")>
  <small class="text-muted">${s.result.fileType?upper_case} (${filesize(s.result.fileSize!0)})</small>
</#if>
html

prettyTime

Utility method for creating human readable timestamps (e.g. "just now", "moments ago", "3 days ago", "within 2 months"). It take one parameter:

  • value: timestamp value

Examples

List search history results and display the date of visit.

<#list session.searchHistory>
  <#items as h>
    <li><a href="?${h.searchParams}">${h.originalQuery!} <small>(${h.totalMatching})</small></a> <span class="text-warning">${prettyTime(h.searchDate)}</span></li>
  </#items>
</#list>
html

removeParam

Remove a set of parameters from a query string. It takes two parameters:

  • qs: query string

  • paramNames: list of parameters to remove from the string

${removeParam(qs, params)}
html

Freemarker macro

The following macro can also be used to call this function:

<#macro RemoveParams params=[]>
  <#local qs><#nested></#local>
  <#compress>
  ${removeParam(qs, params)}
  </#compress>
</#macro>
html

Examples

Return a link that strips off all the faceted navigation parameters and the start rank from the query string.

<a href="${question.collection.configuration.value("ui.modern.search_link")!}?<@RemoveParams params=question.selectedCategoryValues?keys + ["start_rank"]">${QueryString}</@RemoveParams>">Clear selected filters</a>
html

truncate

Truncate a string on word boundaries. It takes two parameters:

  • value: string to be truncated

  • length: number of characters to be truncated

${truncate(value, length)}
html

Freemarker macro

The following macro can also be used to call this function:

<#macro Truncate length><#compress>
  <#local value><#nested></#local>
  ${truncate(value, length)}
</#compress></#macro>
html

Examples

Return the first 140 characters of the result title.

<#import "/web/templates/modernui/funnelback_classic.ftl" as s/>
<@s.Truncate length=140>${s.result.title}</@s.Truncate>
html

urlDecode

Decode a string that has been URL encoded. It takes one parameter:

  • value: the value of URL to be decoded

${urlDecode(value)}
html

Examples

${urlDecode(h.searchParams)}
html

currentProfileConfig.get

Get the configuration value for the given property name for the current collection/profile combination or null if it is not set:

  • name: key of property to retrieve

${question.currentProfileConfig.get(name)}
html
this function will retrieve the configuration setting regardless of if it is set at the profile or collection-level or set globally.

Examples

Get the value of ui.modern.search_link configuration key.

<form class="quicklinks" action="${question.currentProfileConfig.get("ui.modern.search_link")}" method="GET">
  ...
</form>
html

configuration.value

Get the configuration value for the given property name for the current collection or null if it is not set. It may take two parameters:

  • name: key of property to retrieve

  • defaultValue: if value of property is not defined or is not parseable, return this value (optional)

${question.collection.configuration.value(name)}
html
this function will not retrieve any settings that are specified in the profile configuration (profile.cfg).

Examples

Get the value of ui.modern.search_link configuration key.

<form class="quicklinks" action="${question.collection.configuration.value("ui.modern.search_link")}" method="GET">
  ...
</form>
html

configuration.valueAsBoolean

Get the configuration value as a boolean, or the default value if property is not parseable. It may take two parameters:

  • name: key of property to retrieve (required)

  • defaultValue: if value of property is not defined or is not parseable, return this value (optional)

${question.collection.configuration.valueAsBoolean(name)}
html
this function will not retrieve any settings that are specified in the profile configuration (profile.cfg).

Examples

Display search history data if session is enabled.

<#if question.collection.configuration.valueAsBoolean("ui.modern.session")>
  ...
</#if>
html

configuration.valueAsInt

Get the configuration value as a integer, or the default value if property is not parseable. It may take four parameters:

  • name: key of property to retrieve (required)

  • defaultValue: if value of property is not defined or is not parseable or if range is defined and value is not within range, return this value (optional)

  • minValue: The minimal acceptable value (optional)

  • maxValue: The maximum acceptable value (optional)

${question.collection.configuration.valueAsInt(name)}
html
this function will not retrieve any settings that are specified in the profile configuration (profile.cfg).

Example

Get the value of the ui.modern.session.search_history.size configuration key.

${question.collection.configuration.valueAsInt("ui.modern.session.search_history.size ")}
html

httpRequest.getHeader

Provides access to HTTP headers that are part of the search request. Takes a single parameter:

  • h: HTTP header name

${httpRequest.getHeader(h)}
html

Example

Reads a custom HTTP header attribute (X-Funnelback-form) and uses it for a condition within an if statement:

<#ftl encoding="utf-8" />
<#import "/web/templates/modernui/funnelback_classic.ftl" as s/>
<#import "/web/templates/modernui/funnelback.ftl" as fb/>
<html lang="en">
     <head>
         <#assign mtype=httpRequest.getHeader('X-Funnelback-form')>
         <#if mtype == "mobile">
             <#include "simple-mobile.ftl">
         <#else>
             <#include "simple-basic.ftl">
        </#if>
     </head>
     <body></body>
</html>
html

See also