Help Center

Menu

Modern UI utility functions

There are several helper functions that are available for use within Freemarker templates and plugin Java code.

Utility 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 (string)

  • paramName: name of the parameter to be changed (string)

  • value: the new value of the parameter to be set (string)

ensure the query string contains only the set of parameters and values and must not include a leading ?. e.g. collection=example~sp-search&profile=search. 
${changeParam(qs, paramName, value)}

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>

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 (string)

ensure the query string contains only the set of parameters and values and must not include a leading ?. e.g. collection=example~sp-search&profile=search. 
${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>

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 (string)

  • paramNames: list of names of the facet constraint parameters to remove (list/sequence)

ensure the query string contains only the set of parameters and values and must not include a leading ?. e.g. collection=example~sp-search&profile=search. 
${facetScopeRemove(qs, paramNames)}

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>

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>

filesize

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

  • value: file size

${filesize(value)}

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>

prettyTime

Utility method for creating human readable timestamps (for example, "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>

removeParam

Utility method used to remove one or more query string parameters. It takes two parameters:

  • qs: query string (string)

  • paramNames: list of parameters to be removed (list/sequence)

ensure the query string contains only the set of parameters and values and must not include a leading ?. e.g. collection=example~sp-search&profile=search. 
${removeParam(qs, paramNames)}

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>

Examples

Display a "Reset" link which removes the search query and start rank parameters.

<li><a href="${removeParam(QueryString, ["query"]+["start_rank"])}">Reset</a></li>

Remove a custom dateFilter parameter from the faceted navigation clear all facets link.

<li><a href="${response.facetExtras.unselectAllFacetsUrl[1..], ["dateFilter"])}">Clear all</a></li> (1)
1 Note that when using the unselectAllFacets value you must remove the leading ? from the query string. This is performed using the Freemarker string slice function.

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>

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)}

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>

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>

urlDecode

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

  • value: the value of URL to be decoded

${urlDecode(value)}

Examples

${urlDecode(h.searchParams)}

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)}
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>

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)}
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>

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)}
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>

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)}
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 ")}

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)}

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>

See also