Search template customisation

Editing the default template

To edit the default simple.ftl template for a service using the administration interface built-in editor:

Select the collection you wish to modify in the manage collection section of the administration home page
In the customise tab click on the edit result templates link.
This will take you to a listing of the preview templates for the service along with buttons to add, edit, publish and delete templates
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:

Manage configuration files, templates and web resources using WebDAV

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 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.