Skip to content

Search template customisation

Editing the default template

To edit the default simple.ftl template for a collection:

  1. Select the collection you wish to modify in the manage collection section of the administration home page
  2. In the customise tab click on the design results link.
  3. This will take you to the edit form page (shown below), which allows you to edit the template directly.

Edit-simple-form.png

Template editor shortcuts

The built-in template editor has a number of keyboard shortcuts that can assist with editing.

OptionWindowsMacintosh
Toggle full-screen code editing modeF11F11
Toggle data model picker (not in full screen editing mode)F10F10
Save (but don’t publish) changesCtrl+Scontrol ⌃+S
Save and publish changesCtrl+Shift+Scommand ⌘+S
Jump to a line numberCtrl+Lcommand ⌘+L
Find (execute it twice to find/replace)Ctrl+Fcommand ⌘+F

Managing templates

To access other templates or create a new one:

  1. Select the collection you wish to modify in the select collection section of the administration home page
  2. Click on the administer tab
  3. Click on the browse collection configuration files link
  4. This will take you to the file-manager page (shown below)

File-manager-live-preview.png

This shows two sections:

  • Live: Files that are currently live
  • Preview: Files that can be edited and previewed without affecting the live files. The "preview" files will need to be published to move into the "live" area.

From this page, you can select an existing template to modify (e.g. simple.ftl), or create a new custom template file (see create button). The search link allows you to view what the template looks like when generated, and you can also download the templates for editing on your desktop.

Creating additional templates

Multiple templates can be configured for each Funnelback search. Different templates may be used to format results for different use cases that require different formatting (e.g. general search, publications search) or to return the results in other formats (e.g. return the results formatted as a CSV file).

The default template for any collection or service in Funnelback is the simple.ftl template. Additional templates with arbitrary file names can be defined.

Search results templates in Funnelback usually have the following overall logic:

if (search has not been performed)
    display empty search input box and branding
else
    display a search refinement box
    if (search has matching results)
        for each matching result
            display result
    else
        display zero results message

Customising the search results block

Search results are templated according to the code that appears within the <@s.Results> block of code.

<@s.Results>
<#if s.result.class.simpleName != "TierBar">
CODE FOR EACH RESULT
</#if>
</@s.Results>

Basic results item variables available:

  • s.result.title: the result title
  • s.result.summary: the result summary
  • s.result.liveUrl: the URL of the target document
  • s.result.clickTrackingUrl: the URL to use for link actions to make use of Funnelback’s click tracking feature.
  • s.result.cacheUrl: the URL to use to access the cached version of the document
  • s.result.date: the date associated with the document.
  • s.result.fileType: the file type of the document
  • s.result.rank: the position (rank) of the current result item inside the result set.
  • s.result.metaData: map of metadata elements available for use in templates. Includes only metadata fields that have been configured (using display options) to be returned with the search results.

To print any of these values wrap them in the Freemarker directive ${VARIABLENAME}. E.g. ${s.result.title} will be replaced with the title text for the current result.

Before accessing any variable ensure that the variable being printed is defined:

  • by wrapping the variable in an <#if> statement using the missing value operator ??

    	<#if s.result.title??>${s.result.title}<#else>No title</#if>
    
  • or for cases where you are printing variable without surrounding markup an exclamation mark (!) can be used e.g ${VARIABLENAME!}

    • ${s.result.title}: the template returns an error if variable is not defined.
    • ${s.result.title!}: prints the title variable if set otherwise nothing
    • ${s.result.title!"Empty"}: prints the title variable if set otherwise prints Empty.

The data model - an introduction

Behind every search page is a highly detailed data structure containing all the data relating to the search transaction. This data structure, known as the data model, contains information relating to the search query, response and configuration. Every element that is returned in the data model can be utilised by the search template.

Top-level structure

The Funnelback data model consists of two main objects:

  • question: includes all of the data defining the search question. This includes the search keywords, the collection, configuration, ranking and display options, and other search constraints.
  • response: the response contains all of the information returned by the Funnelback query processor in response to the question object. This includes the search results and associated metadata, faceted navigation and result counts, spelling suggestions, best bets etc.

Data model types

The value component of an item in the data model indicates the data type of the field. Funnelback fields are one of the following types:

  • String: indicated by double quotes e.g. title: "example"
  • Number: indicated by an integer without quotes e.g. rank: 0
  • Sequence: (array/list) indicated by square brackets e.g. selectedFacets: []
  • Hash: (map/associative array) indicated by curly brackets e.g. environmentVariables: {}

Setting a custom MIME type for a template

Funnelback can be configured to return a custom MIME type for a template by setting a configuration option in the profile.cfg for the profile containing the template.

See: ui.modern.form.TEMPLATE.content_type

Setting a custom HTTP headers for a template

In addition to the content type, custom HTTP headers can also be defined using similar configuration options.

See:

See also

top

Funnelback logo
v15.16.0