NAVIGATION

funnelback.ftl

Description

New search tags for the Public UI.

This library contains tags that don't exist in the Classic UI.

They either provide improved functionality over the Classic UI or are related to new features.

Some tags assume that the library has been imported under the fb namespace.

Macro and Function Summary
Uncategorized
`macro`	`AuthToken` Generates an authentication token suitable for click tracking redirection, based on the globally configured `server_secret`.
`macro`	`CheckBlending` `prefix` `linkText` `tag` Checks if a query blending occurred and provide a link to cancel it.
`macro`	`Collapsed` `defaultLabel` `defaultApproximateLabel` `labels` Generates a link to show the results that were collapsed with this specific result.
`macro`	`Format` `args` `str` `key` `locale` Formats a string according to a Locale.
`macro`	`IncludeUrl` `url` `params` Includes content from an an external URL.
`macro`	`Optimise` `label` Generates an "audit SEO" link to the SEO Auditor (From the admin side only)
`macro`	`PerformanceMetrics` `width` `msLabel` `totalLabel` `jsOnly` `class` `tdClass` `title` Displays a table with the time taken by each step in the query lifecycle.
`function`	`renderSize` ( `sz` ) Converts a size to its equivalent in gigabytes, megabytes, or kilobytes as appropriate.
Category Administration
`macro`	`AdminUIOnly` Display content for admins only.
`macro`	`ViewModeBanner` Displays the preview / live banner.
Category Error handling
`macro`	`ErrorMessage` `defaultMessage` Displays search error message.
`macro`	`ErrorMessageJS` `message` `messageData` Displays error messages in the JS console.
Category Extra searches
`macro`	`ExtraResults` `name` Process results coming from an extra search.
`macro`	`ExtraSearch` `question` `collection` `query` `params` Perform an additional search and process results.
Category Multiple facet selection
`macro`	`MultiCategories` `facet` Multiple facet selection: Categories tag.
`macro`	`MultiCategory` `category` `facetSelected` Multiple facet selection: Category tag.
`macro`	`MultiFacet` `name` `names` Multiple facet selection: Facet tag.
`macro`	`MultiValues` `values` `facetSelected` `max` Multiple facet selection: Values tag.
Category Navigation
`macro`	`Next` `link` `startParamName` Generates a link to the next page of results.
`macro`	`Page` `numPages` `link` `startParamName` Generates links to result pages.
`macro`	`Prev` `link` `startParamName` Generates a link to the previous page of results.
Category Session features
`macro`	`HasClickHistory` Check if the user click history is empty or not.
`macro`	`HasSearchHistory` Check if the user search history is empty or not.
Category Session features (Deprecated in v13)
`macro`	`ClickHistory` `lastClicksLabel` `clearLabel` `max` DEPRECATED in v13: Display the click history
`macro`	`ResultCart` DEPRECATED in v13: Display a link to add a result to the cart
`macro`	`ResultsCart` `savedResultsLabel` `clearLabel` DEPRECATED in v13: Display the result cart
`macro`	`SearchHistory` `lastQueriesLabel` `clearLabel` `resultsLabel` `max` DEPRECATED in v13: Display the search history

Macro and Function Detail

macro AdminUIOnly

Display content for admins only.

Executes nested content only if the page is viewed from the Admin UI service (Based on the HTTP port used)

This is used for example to display the preview / live mode banner.

Category

Administration

Source Code





<#macro AdminUIOnly>
    <#if isAdminUI(Request)>
        <#nested />
    </#if>
</#macro>

macro AuthToken

Generates an authentication token suitable for click tracking redirection, based on the globally configured server_secret.

Nested

URL to generate the token for.

Source Code





<#macro AuthToken><#compress>
    <#assign content><#nested></#assign>
    ${authToken(content)}
</#compress></#macro>

macro CheckBlending prefix linkText tag

Checks if a query blending occurred and provide a link to cancel it.

Parameters

prefix - Prefix to blended query terms, defaults to "Your query has been expanded to: ".
linkText - Text for the link to cancel query blending, defaults to "Click here to use verbatim query". Note that HTML is not allowed here (it will be escaped), however for legacy reasons, emphasis open/close html tags are permitted (and will not be escaped).
tag - Tag to use to wrap the expanded queries.

Source Code





<#macro CheckBlending prefix="Your query has been expanded to: " linkText="Click here to use verbatim query" tag="span">
    <#if response?? && response.resultPacket??
        && response.resultPacket.QSups?? && response.resultPacket.QSups?size gt 0>
        ${prefix} <${tag}><#list response.resultPacket.QSups as qsup> ${qsup.query}<#if qsup_has_next>, </#if></#list></${tag}>.
        &nbsp;<a href="?${QueryString}&amp;qsup=off">${linkText?html?replace("&lt;em&gt;", "<em>")?replace("&lt;/em&gt;", "</em>")}</a>
        <#-- See FUN-9496 for info about the strange replaces above -->
    </#if>
</#macro>

macro ClickHistory lastClicksLabel clearLabel max

DEPRECATED in v13: Display the click history

Category

Session features (Deprecated in v13)

Source Code





<#macro ClickHistory lastClicksLabel="Last results clicked" clearLabel="clear" max=5></#macro>

macro Collapsed defaultLabel defaultApproximateLabel labels

Generates a link to show the results that were collapsed with this specific result.

Parameters

defaultLabel - Label to use when there's no label for the current collapsing column
labels - Text to use for the link. {0} will be replaced by the number of collapsed results. This is a hash where the key is the collapsing column, as a String, for example: <@fb.Collapsed labels={"[X]": "{0} results from the same state", "[Y]": "{0} results from the same employer"} />

Source Code





<#macro Collapsed defaultLabel="{0} very similar results" defaultApproximateLabel="About {0} very similar results" labels={}>
    <#if s.result.collapsed??>
        <#assign text = defaultLabel />
        <#if response.resultPacket.resultsSummary.estimatedCounts>
                <#assign text = defaultApproximateLabel>
        </#if>
        <#if labels[s.result.collapsed.column]??>
            <#assign text = labels[s.result.collapsed.column] />
        </#if>
        <a class="search-collapsed" href="?${removeParam(QueryString, ["start_rank","duplicate_start_rank"])?html}&amp;s=%3F:${s.result.collapsed.signature}&amp;fmo=on&amp;collapsing=off">${text?replace("{0}", s.result.collapsed.count)}</a>
    </#if>
</#macro>

macro ErrorMessage defaultMessage

Displays search error message.

Displays the error to the user and the technical message in an HTML comment + JS console.

Parameters

defaultMessage - Default message to use if there's no detailed error message.

Category

Error handling

Source Code





<#macro ErrorMessage defaultMessage="An unknown error has occurred. Please try again">
    <#-- PADRE error -->
    <#if response?? && response.resultPacket?? && response.resultPacket.error??>
        <p class="search-error">${response.resultPacket.error.userMsg!defaultMessage?html}</p>
        <!-- PADRE return code: [${response.returnCode!"Unknown"}], admin message: ${response.resultPacket.error.adminMsg!?html} -->
        <@ErrorMessageJS message="PADRE return code: "+response.returnCode!"Unknown" messageData=response.resultPacket.error.adminMsg! />
    </#if>
    <#-- Other errors -->
    <#if error??>
        <!-- ERROR status: ${error.reason!?html} -->
        <#if error.additionalData??>
            <p class="search-error">${error.additionalData.message!defaultMessage?html}</p>
            <!-- ERROR cause: ${error.additionalData.cause!?html} --> 
            <@ErrorMessageJS message=error.additionalData.message! messageData=error.additionalData.cause! />
        <#else>
            <p class="search-error">${defaultMessage}</p>
        </#if>
    </#if>
</#macro>

macro ErrorMessageJS message messageData

Displays error messages in the JS console.

Parameters

message - Message to display.
messageData - Additional data to display.

Category

Error handling

Source Code





<#macro ErrorMessageJS message="" messageData="">
    <script type="text/javascript">
        try {
            console.log("Funnelback: " + "${message?js_string}");
            console.log("Funnelback: " + "${messageData?js_string}");
        } catch (ex) {
        }
    </script>
</#macro>

macro ExtraResults name

Process results coming from an extra search.

The extra search needs to be properly configured in collection.cfg for the results to be available.

Extra searches are run in parallel of the main query and take advantage of multi-core machines. It's recommended to use it rather than @fb.ExtraSearch

An example configuration is:

Create extra search config file ($SEARCH_HOME/conf/$COLLECTION_NAME/extra_search..cfg)
collection=<collection name to search>
query_processor_options=-num_ranks3
Reference extra search config in collection.cfg
ui.modern.extra_searches=<extra search name>

Add extra search form code to search template

 <div id="extraSearch">
 <@fb.ExtraResults name="<extra search name>">
 <#if response.resultPacket.results?size < 0>
 <h3>Related news>/h3>
 <#list response.resultPacket.results as result>
 <p class="fb-extra-result">
 ${result.title}
 </p>
 </#list>
 </div>
 </#if>
 </@fb.ExtraResults>
 </div>

Parameters

name - Name of the extra search results to process, as configured in collection.cfg.

Category

Extra searches

Source Code





<#macro ExtraResults name>
    <#if extraSearches?? && extraSearches[name]??>
        <#local questionBackup = question!{} />
        <#local responseBackup = response!{} />
        <#if error??>
            <#local errorBackup = error />
        </#if>

        <#global question = extraSearches[name].question!{} />
        <#global response = extraSearches[name].response!{} />
        <#if extraSearches[name].error??>
            <#global error = extraSearches[name].error />
        </#if>

        <#nested>

        <#global question = questionBackup />
        <#global response = responseBackup />
        <#if errorBackup??>
            <#global error = errorBackup />
        </#if>
    <#else>
        <!-- No extra results for '${name}' found -->
    </#if>
</#macro>

macro ExtraSearch question collection query params

Perform an additional search and process results.

The data can then be accessed using the standard question, response and error objects from within the tag.

Note that the search is run when the tag is actually evaluated. This could impact the overall response time. For this reason it's recommended to use @fb.ExtraResults.

Parameters

question - Initial SearchQuestion, used as a base for parameters.
query - Query terms to search for.
collection - Name of the collection to search on.
params - Map of additional parameters (ex: {"num_ranks" : "3"}).

Category

Extra searches

Source Code





<#macro ExtraSearch question collection query params={}>
    <#local questionBackup = question!{} />
    <#local responseBackup = response!{} />
    <#local errorBackup = error!{} />
    <#local extra = search(question, collection, query, params)>
    <#global question = extra.question!{} />
    <#global response = extra.response!{} />
    <#global error = extra.error!{} />
    <#nested>
    <#global question = questionBackup />
    <#global response = responseBackup />
    <#global error = errorBackup />
</#macro>

macro Format args str key locale

Formats a string according to a Locale.

This tag is usually used with internationalisation.

Either key or str must be provided. Using key will lookup the corresponding translation key in the data model. Using str will format the str string directly.

When key is used, str can be used with it as a fallback value if the key is not found in the data model. For example <@fb.Format key="results" str="Results for %s" args=[question.query] /> will lookup the key results in the translations. If the key is not present, then the literal string Results for %s will be used instead.

See the Modern UI localisation guidelines for more information and examples.

Parameters

str - Use a literal string instead of a translation key. For example "%d results match the query %s". See java.util.Formatter for the format specifier documentation.
args - Array of arguments to be formatted, for example [42, "funnelback"].
locale - The java.util.Locale to use, defaults to the current Locale in the question.
key - Takes the string to format from the translations in the data model (response.translations).

Source Code





<#macro Format args=[] str="" key="" locale=question.locale>
    <#if key != "">
        <#local s = response.translations[key]!str />
    <#else>
        <#local s = str />
    </#if>

    <#if args??>
        ${format(locale, s, args)}
    <#else>
        ${format(locale, s)}
    </#if>
</#macro>

macro HasClickHistory

Check if the user click history is empty or not. Writes 'true' if it is, 'false' otherwise.

Category

Session features

Source Code





<#macro HasClickHistory><#if session?? && session.clickHistory?size gt 0>true<#else>false</#if></#macro>

macro HasSearchHistory

Check if the user search history is empty or not. Writes 'true' if it is, 'false' otherwise.

Category

Session features

Source Code





<#macro HasSearchHistory><#if session?? && session.searchHistory?size gt 0>true<#else>false</#if></#macro>

macro IncludeUrl url params

Includes content from an an external URL. Replacement for NickScript's IncludeUrl plugin Supports HTTP redirects, however 'meta@paramrefresh' tags/redirects within the included url are not supported.

Content is cached to avoid firing an HTTP request for each search results page.

Note that the CSS selectors supported are only those that are supported by Jsoup.

when CSS selectors are used the document will be modified by Jsoup. For example when given:

<div><p>foo</p></div>

Jsoup will transform that to:

 <html> <head> </head> <body> <div><p>foo</p></div> </body> </html>

Parameters:

Parameters

password - : Password if the remote resource require authentication
convertRelativeRequiresSpace - : boolean, while attempting to convert relative links, if `true`, requires there is a space between HTML attributes in the link. By default, `true`.
removeByCssSelectors - : A list of CSS selectors which match elements to be removed from the included HTML. This is run after 'cssSelector', and so if 'cssSelector' is used the CSS selectors must be relative to the previously selected element. If 'cssSelector' is not used the HTML may be slightly modified to be a valid HTML document before elements are removed. See above for more information about Jsoup modification.
start - : Regex pattern to consider to start including content
useragent - : Override default user agent
end - : Regex pattern to consider to end including content
expiry - : Cache TTL, in seconds
convertRelative - : boolean, whether relative links in the included content should be converted to absolute ones.
url - : Absolute URL to include
timeout - : Time to wait in seconds for the remote resource
username - : Username if the remote resource require authentication
cssSelector - : CSS selector to use to select the HTML which should be included. The selected element will be the first one to match the selector. The HTML returned will include the element and its attributes. When this option is enabled the document may be slightly modified to be a valid HTML document before the cssSelector is applied this includes wrapping in '<html>' tags and '<body>' tags. See above for more information about Jsoup modification.

Source Code





<#macro IncludeUrl url params...>
    <@IncludeUrlInternal url=url
        expiry=params.expiry
        start=params.start
        end=params.end
        username=params.username
        password=params.password
        useragent=params.useragent
        timeout=params.timeout
        convertRelative=params.convertRelative
        convertrelative=params.convertrelative
        cssSelector = params.cssSelector
        removeByCssSelectors = params.removeByCssSelectors
        convertRelativeRequiresSpace=params.convertRelativeRequiresSpace
        />
</#macro>

macro MultiCategories facet
⚠ Deprecated: The new facets data model has been simplified and can be used directly with native FreeMarker tags

macro MultiCategory category facetSelected
⚠ Deprecated: The new facets data model has been simplified and can be used directly with native FreeMarker tags

macro MultiFacet name names
⚠ Deprecated: The new facets data model has been simplified and can be used directly with native FreeMarker tags

macro MultiValues values facetSelected max
⚠ Deprecated: The new facets data model has been simplified and can be used directly with native FreeMarker tags

macro Next link startParamName

Generates a link to the next page of results.

Example:

<@fb.Next> <a href="${fb.nextUrl}">Next ${fb.nextRanks} results</p></@fb.Next>

Provides

The URL of the next page, as ${fb.nextUrl}, the number of results on the next page, as ${fb.nextRanks}.

Category

Navigation

Source Code





<#macro Next link=question.currentProfileConfig.get("ui.modern.search_link") startParamName="start_rank">
    <#if response?? && response.resultPacket?? && response.resultPacket.resultsSummary??>
        <#if response.resultPacket.resultsSummary.nextStart??>
            <#assign nextUrl = link + "?"
                + changeParam(QueryString, startParamName, response.resultPacket.resultsSummary.nextStart) in fb />
            <#assign nextRanks = response.resultPacket.resultsSummary.numRanks in fb />
            <#nested>
        </#if>
    </#if>
</#macro>

macro Optimise label

Generates an "audit SEO" link to the SEO Auditor (From the admin side only)

Parameters

label - Text to use for the link.

Source Code





<#macro Optimise label="Audit SEO">
    <@AdminUIOnly>
        <a class="search-optimise" href="/a/#/${s.result.collection}:${question.profile}/analyse/seo-auditor/${response.resultPacket.query?url}/${urlEncodeFragment(s.result.indexUrl)?replace("/", "%252F")}">${label}</a>
    </@AdminUIOnly>
</#macro>

macro Page numPages link startParamName

Generates links to result pages.

Iterate over the nested content for each available page

Three variables will be set in the template:

fb.pageUrl: Url of the page.
fb.pageCurrent: boolean, whether the current page is the one currently displayed.
fb.pageNumber: Number of the current page.

Example:

<@fb.Page> <#if fb.pageCurrent> ${fb.pageNumber} <#else> <a href="${fb.pageUrl}">${fb.pageNumber}</a> </#if></@fb.Page>

Parameters

numPages - Number of pages links to display (default = 10)

Category

Navigation

Source Code





<#macro Page numPages=10 link=question.currentProfileConfig.get("ui.modern.search_link") startParamName="start_rank">
    <#local rs = response.resultPacket.resultsSummary />
    <#local pages = 0 />
    <#if rs.fullyMatching??>
        <#if rs.fullyMatching gt 0>
            <#local pages = (rs.fullyMatching + rs.partiallyMatching + rs.numRanks - 1) / rs.numRanks />
        <#else>
            <#local pages = (rs.totalMatching + rs.numRanks - 1) / rs.numRanks />
        </#if>
    <#else>
        <#-- Event search -->
        <#local pages = (rs.totalMatching + rs.numRanks - 1) / rs.numRanks />
    </#if>

    <#local currentPage = 1 />
    <#if rs.currStart gt 0 && rs.numRanks gt 0>
        <#local currentPage = (rs.currStart + rs.numRanks -1) / rs.numRanks />
    </#if>

    <#local firstPage = 1 />
    <#if currentPage gt ((numPages-1)/2)?floor>
       <#local firstPage = currentPage - ((numPages-1)/2)?floor />
    </#if>

    <#list firstPage..firstPage+(numPages-1) as pg>
        <#if pg gt pages><#break /></#if>
        <#assign pageNumber = pg in fb />
        <#assign pageUrl = link + "?" + changeParam(QueryString, startParamName, (pg-1) * rs.numRanks+1) in fb />

        <#if pg == currentPage>
            <#assign pageCurrent = true in fb />
        <#else>
            <#assign pageCurrent = false in fb />
        </#if>
        <#nested>

    </#list>
</#macro>

macro PerformanceMetrics width msLabel totalLabel jsOnly class tdClass title

Displays a table with the time taken by each step in the query lifecycle.

Parameters

totalLabel - Label to use for the "Total" summary row
width - Width in pixels to use for the bar graphs
jsOnly - Do not display the metrics, only output the processing time in the JS console.
msLabel - Label to use for "milliseconds"

Source Code





<#macro PerformanceMetrics width=500 msLabel="ms" totalLabel="Total" jsOnly=false class="search-metrics" tdClass="" title="<h3>Performance</h3>">
    <#if response?? && response.performanceMetrics??>
        <#if response.performanceMetrics.isRunning() >
          ${response.performanceMetrics.stop()}
        </#if>
        <script>
            try {
                console.log("Query processing time: ${response.performanceMetrics.totalTimeMillis} ${msLabel}");
            } catch (ex) {
            }
        </script>
        <#if ! jsOnly>
            <#assign scale= width / response.performanceMetrics.totalTimeMillis />
            <#assign offset=0 />

            ${title}

            <table class="${class}">
            <thead>
                <tr>
                    <th>Component</th>
                    <th>Time</th>
                    <th>Chart</th>
                </tr>
            </thead>
            <tbody>
            <#list response.performanceMetrics.taskInfo as ti>
                <#assign timeTaken = ti.timeMillis * scale />
                <#assign kv = (ti.taskName!":")?split(":") />
                <#assign valueClass=kv[0]! />
                <#assign name=kv[1]! />
                <tr>
                    <td>${name}</td>
                    <td>${ti.timeMillis!} ${msLabel}</td>
                    <td><div class="metric ${tdClass} ${valueClass}" style="width: ${timeTaken?round}px; margin-left: ${offset}px;">&nbsp;</div></td>
                </tr>
                <#assign offset = offset+(timeTaken) />
            </#list>
                <tr>
                    <th>${totalLabel}</th>
                    <th colspan="2">${response.performanceMetrics.totalTimeMillis} ${msLabel}</th>
                </tr>
            </tbody>
            </table>
        </#if>
    </#if>
</#macro>

macro Prev link startParamName

Generates a link to the previous page of results.

Example:

<@fb.Prev> <a href="${fb.prevUrl}">Previous ${fb.prevRanks} results</p></@fb.Prev>

Provides

The URL of the previous page, as ${fb.prevUrl}, the number of results on the previous page, as ${fb.prevRanks}.

Category

Navigation

Source Code





<#macro Prev link=question.currentProfileConfig.get("ui.modern.search_link") startParamName="start_rank">
    <#if response?? && response.resultPacket?? && response.resultPacket.resultsSummary??>
        <#if response.resultPacket.resultsSummary.prevStart??>
            <#assign prevUrl = link + "?"
                + changeParam(QueryString, startParamName, response.resultPacket.resultsSummary.prevStart) in fb />
            <#assign prevRanks = response.resultPacket.resultsSummary.numRanks in fb />
            <#nested>
        </#if>
    </#if>
</#macro>

function renderSize ( sz )

Converts a size to its equivalent in gigabytes, megabytes, or kilobytes as appropriate. kilobytes are rounded to no decimal places, giga and mega take one decimal place. Conversion is done by 1024, not 1000. returns a string

Source Code





<#function renderSize sz>
    <#local giga = 1024 * 1024 * 1024>
    <#local mega = 1024 * 1024>
    <#local kilo = 1024>
    <#if (sz > giga) >
        <#return (sz / giga)?string[".#"] + "&nbspGB">
    <#elseif (sz > mega)>
        <#return (sz / mega)?string[".#"] + "&nbspMB">
    <#elseif (sz > kilo)>
        <#return (sz / kilo)?int + "&nbspKB">
    <#else>
        <#return sz + "&nbspB">
    </#if>
</#function>

macro ResultCart

DEPRECATED in v13: Display a link to add a result to the cart

Category

Session features (Deprecated in v13)

Source Code





<#macro ResultCart></#macro>

macro ResultsCart savedResultsLabel clearLabel

DEPRECATED in v13: Display the result cart

Category

Session features (Deprecated in v13)

Source Code





<#macro ResultsCart savedResultsLabel="Saved results" clearLabel="clear"></#macro>

macro SearchHistory lastQueriesLabel clearLabel resultsLabel max

DEPRECATED in v13: Display the search history

Category

Session features (Deprecated in v13)

Source Code





<#macro SearchHistory lastQueriesLabel="Last queries" clearLabel="clear" resultsLabel="results" max=5></#macro>

macro ViewModeBanner

Displays the preview / live banner.

Displays the banner to switch between live and preview mode for the current form. Use AdminUIOnly to display it only from the Admin UI service.

Category

Administration

Source Code





<#macro ViewModeBanner>
    <@AdminUIOnly>
        <#local style="padding: 5px; font-family: Verdana; text-align: right; border: solid 2px #aaa; font-size: small;" />
        <#local returnTo=ContextPath+"/"+question.currentProfileConfig.get("ui.modern.search_link")+"?"+QueryString />
        <#if question.profile?ends_with("_preview")>
            <div id="funnelback_form_mode" style="background-color: lightblue; ${style}">
                &middot; <a href="${SearchPrefix}../d/manage/${question.collection.id}:${question.profile?replace("_preview", "")}/files/detail?path=preview%2Ftemplates%2F${question.form}.ftl" title="Edit this form">edit form</a>
                &middot; <a href="?${changeParam(QueryString, 'profile', question.profile?replace("_preview", ""))?html}" title="View this search with the current live form">switch to live mode</a>
                | <span title="This form file may be edited before publishing to external search users">preview mode</span> 
            </div>
        <#else>
            <div id="funnelback_form_mode" style="background-color: lightgreen; ${style}">
                <a href="?${changeParam(QueryString, 'profile', question.profile+'_preview')?html}" title="View this search with the current preview form">switch to preview mode</a>
                | <span title="This form file is currently published for external search users">live mode</span> 
            </div>
        </#if>
    </@AdminUIOnly>
</#macro>