Help Center

Menu

Search template customization

Editing the default template

To edit the default simple.ftl template for a results page using the search dashboard built-in editor:

  1. Select the results page you wish to modify and then edit the result page configuration of the administration home page

  2. In the template section select the edit results page templates option.

  3. This will take you to a listing of the preview templates for the results page along with buttons to add, edit, publish and delete templates.

  4. Clicking the name of any listed template takes you to an editing screen,which allows you to edit the template directly.

Alternatively search templates can also be created and edited in the editor of your choice by accessing Funnelback through a compatible WebDAV client.

See:

Template editor shortcuts

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

Option Windows Macintosh

Save (without publishing) changes

Ctrl+S

control ⌃+S

Find (then click the lower-left '+' button to replace)

Ctrl+F

command ⌘+F

Jump to line (Note: only supported in some browsers)

Ctrl+L

command ⌘+L

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 results page in Funnelback is the simple.ftl template. Additional templates with arbitrary 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

By default, the Funnelback search box includes a single text entry box for the search query terms, a button to submit the search results and is configured for auto-completion.

This search form can be customized to provide advanced search capabilities.

See: the Search CGI parameters section of the query language help for fields that you can include in a search form.

This Funnelback template snippet will display a HTML input box that allows the user to search for a particular phrase (via the _phrase modifier).

...
<label for="query_phrase">Search:</label>
<input id="query_phrase"
       type="text" name="query_phrase"
       value="${question.inputParameters["query_phrase"]?first!?html}"
       placeholder="e.g. to be or not to be">
...

Example 2: Funnelback "advanced" search form

The following template snippet is from a sample Funnelback advanced search form. It provides HTML for four text boxes for the user to enter terms to find:

  • all the words ( _and );

  • a phrase ( _phrase );

  • any of the words ( _or );

  • none of the words ( _not ).

 ...
<dl>
  <!-- all the words -->
  <dt>
      <label for="query_and">All the words:</label>
  </dt>
  <dd>
      <input type="text"
             id="query_and"
             name="query_and"
             value="${question.inputParameters["query_and"]?first!?html}">
  </dd>

  <!-- the phrase -->
  <dt>
      <label for="query_phrase">The phrase:</label>
  </dt>
  <dd>
      <input type="text"
             id="query_phrase"
             name="query_phrase"
             value="${question.inputParameters["query_phrase"]?first!?html}">
  </dd>

  <!-- any of the words -->
  <dt>
      <label for="query_or">Any of the words:</label>
  </dt>
  <dd>
      <input type="text"
             id="query_or"
             name="query_or"
             value="${question.inputParameters["query_or"]?first!?html}">
  </dd>

  <!-- none of the words -->
  <dt>
      <label for="query_not">None of the words:</label>
  </dt>
  <dd>
  <input type="text"
         id="query_not"
         name="query_not"
         value="${question.inputParameters["query_not"]?first!?html}">
  </dd>
</dl>
...

Customizing 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. Note: The clean title plugin allows you to modify the result title.

  • s.result.summary: the result summary

  • s.result.liveUrl: the URL of the target document. Note: The alter live URL plugin allows you to modify the result’s URL.

  • s.result.click: TrackingUrl: 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.listMetadata: 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 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 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.

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 results page configuration for the results page containing the template.

See: ui.modern.form.TEMPLATE.content_type

Setting 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