Auto Completion (collection.cfg)

Description

This option can be used to enable or disable Funnelback's auto completion feature. When set to 'enabled', auto completion of queries will be performed, while any other value (normally 'disabled') will disable auto completion.

Auto Completion Details

Funnelback's system for suggesting completions as the searcher types characters into the search box relies on both Javascript functions in the user interface and an efficient back-end for making suggestions in response to a partial query.

Suggestions can either come from the collection Spelling Suggestions, Best Bets, or from a custom CSV file.

Spelling Suggestions

Using the Spelling Suggestions file allows out-of-the-box suggestions from the collection data without any configuration step required. This file is built by the build_spelling_index program which can be instructed to derive suggestions from various sources and to apply user-controllable criteria for inclusion. Suggestions are only included if they match the collection and are given a weight based on frequency of occurrence. Typical sources of suggestions are the corpus lexicon (single words), document annotations (such as anchortext, clicked queries, etc.), document titles and possibly other metadata fields.

QueryCompletionPublicUI.png

Best bets

Using the Best bets file allows to quickly build a suggestion list using the Best bets editor.

Please note that only Exact query match best bets will be considered. All auto completion entries from best bets have a weight of 100.0.

Custom CSV data

Using a custom CSV file as a suggestion source allows you to build your own suggestions and include extra data not present in the collection. This mode also enable complex suggestions to be displayed (HTML fragments, Javascript callbacks, etc.) and complex actions to be performed when a suggestion is selected (Run a query, open a URL, run a Javascript function, etc.).

QueryCompletionExtendedPublicUI.png

For more information about custom CSV data, please see the CSV Data section.

Scoped Auto Completion

Auto completion will be automatically scoped for each profile to prevent suggesting queries that would show no results in that profile. This works using the query processor options specified in the padre_opts.cfg file for the profile (if there is one). If the padre_opts.cfg file is not present, then auto completion suggestions are not scoped.

If a profile contains scope query processor options such as gscopes in its padre_opts.cfg file, auto completion suggestions are only generated for queries that return results once that scoping is applied.

Note that rich auto completion suggestions are never scoped - they will always be suggested to the user. Profile-based auto-completion.csv file is not supported at this point.

Default value

auto-completion=disabled

Examples

To turn on auto completion:

auto-completion=enabled

In order to add auto completion to the search box on your website you need to add some javascript code to your page header.

You can copy the required javascript from the html returned by Funnelback when you run a search on your site, but will need to check that the URL paths are absolute. It should look something like the code below.

Note: you need to ensure that:

  • paths to the javascript files are correct
  • version numbers for jQuery and jQuery UI are set. You can compare with the versions that ship with Funnelback under SEARCH_HOME/web/public/js/jquery/
  • the jquery.funnelback-completion.js code is included after any jquery libraries are loaded
  • the Funnelback search.css (or relevant CSS rules to handle the auto completion styling) is included
  • the jQuery("input.query").fbcompletion() call is matched to the html input element for the search box (ie. for the example below you need to set a class of 'query' on your search input box).
<link rel="stylesheet" media="screen" href="http://funnelback.server/search/search.css" type="text/css" />
<script type="text/javascript" src="http://code.jquery.com/jquery-X.Y.Z.min.js"></script>
<script type="text/javascript" src="http://code.jquery.com/ui/X.Y.Z/jquery-ui.min.js"></script>
<script type="text/javascript" src="http://funnelback.server/search/js/jquery/jquery.tmpl.min.js"></script>
<script type="text/javascript" src="http://funnelback.server/search/js/jquery.funnelback-completion.js"></script>
<script type="text/javascript">
// Auto completion setup.
  jQuery(function() {
  jQuery("input.query").fbcompletion({
    'enabled'    : 'enabled',
    'collection' : 'collection_name',
    'program'    : 'http://funnelback.server/s/suggest.json',
    'format'    : 'extended',
    'alpha'      : '.5',
    'show'       : '10',
    'sort'       : '0',
    'length'     : '3',
    'delay'      : '0'
    });
  });
</script>

Customising (Styling) Auto Completions

Customising the visual design ('look and feel') of the auto completion suggestions is most efficiently achieved by copying the default Funnelback CSS and Javascript code and then modifying to suit your needs. If your Funnelback search form template already uses custom CSS, then the auto completion suggestions will inherit those styles and may only require minor style modifications. The auto completion system is based on the jQuery UI Autocomplete widget, so reading the CSS guide for jQuery UI might also be useful.

When customising auto completion styling, we recommend the following:

  • Using a browser extension that allows you to inspect and modify CSS in real-time (e.g. the Firebug extension for Firefox). Firebug is especially useful for viewing the HTML generated by Jquery, which is not otherwise visible when viewing the HTML source code.
  • Any required additional HTML structures (e.g. adding a custom span around matching suggestions, within the HTML), can be added in the auto-completion.csv file.
  • Any additional Jquery libraries referenced in the search form template may cause incompatibilities with the Funnelback auto completion functions. Firebug will provide a list of errors encountered when rendering a page and is a quick way to diagnose this issue. If multiple libraries are required, then moving the Funnelback Jquery script tags to the end of the head section may resolve the issue. A more complete solution would be to re-generate the Jquery libraries, with the required Autocomplete functions required by Funnelback.

An example customisation workflow is:

  1. Copy the auto completion CSS from funnelback.server/search/search.css to a custom CSS file. The relevant CSS is marked with an opening comment of /* AUTO COMPLETION - Uses jquery-ui */.
  2. Refresh the search template to see how auto completion suggestions are displayed.
  3. Modify or create CSS rules as required, in your browser, using Firebug (or Chrome developer tools).
  4. Add the CSS rules to your custom CSS file.

top