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:
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 titles.result.summary
: the result summarys.result.live
Url: the URL of the target documents.result.click
TrackingUrl: the URL to use for link actions to make use of Funnelback’s click tracking feature.s.result.cache
Url: the URL to use to access the cached version of the documents.result.date
: the date associated with the document.s.result.file
Type: the file type of the documents.result.rank
: the position (rank) of the current result item inside the result set.s.result.meta
Data: 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:
ui.modern.form.TEMPLATE.headers.HEADER
- Add custom HTTP headers to a specific template.ui.modern.form.TEMPLATE.remove-headers
- Remove custom HTTP headers from a specific template.