Skip to content

Auto-completion frontend

Basic setup

In order to add auto-completion to the search box on your website you need to add some JavaScript code and CSS styling to your page.

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 and CSS files are correct
  • version numbers for jQuery are set. You can compare with the versions that ship with Funnelback under $SEARCH_HOME/web/public/js/jquery/
  • the funnelback.autocompletion.js code is included after any jQuery libraries are loaded
  • the Funnelback funnelback.autocompletion.css (or relevant CSS rules to handle the auto-completion styling) is included
  • the jQuery("input.query").autocompletion() 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" type="text/css" href="http://funnelback.server/s/resources-global/css/funnelback.autocompletion.css" />

<script type="text/javascript" src="http://code.jquery.com/jquery-X.Y.Z.min.js"></script>
<script type="text/javascript" src="http://funnelback.server/s/resources-global/js/typeahead.bundle.js"></script>
<script type="text/javascript" src="http://funnelback.server/s/resources-global/js/handlebars.js"></script>
<script type="text/javascript" src="http://funnelback.server/s/resources-global/js/funnelback.autocompletion.js"></script>

<script type="text/javascript">
// Auto completion setup
(function($) {
  $('input.query').autocompletion({
    datasets: {
      organic: {
        collection: 'collection_name',
        profile   : '_default',
        program   : 'http://funnelback.server/s/suggest.json',
      }
    },
    length: 3
  });
})(jQuery);
</script>

Dependencies

The following third party code is used for this implementation:

Configuring the Concierge auto-completion plugin

The Concierge auto-completion plugin is a JavaScript module that is loaded in the search results page (or within a web page on your website) in order to interact with and display auto-completion sourced from Funnelback.

Concierge is configured using the JavaScript auto-completion setup block included within your HTML page (see the auto-completion setup function in the example above).

General configuration

The configuration for Concierge contains some general configuration that applies to all the columns Concierge and a series of datasets, each of which correspond to a single column within Concierge.

Values that are normally set at a global level (applying to all columns) are:

  • datasets: this element contains sub-elements that configure each auto-completion dataset
  • length: the number of keystrokes before any suggestions are returned
  • hint: whether or not the search box displays a greyed out hint as placeholder text
  • scrollable: whether or not the auto-complete dropdown includes a scrollbar

The rest of the settings are usually defined per dataset, within the datasets element, however most can also be defined at a global level.

jQuery('input.query').autocompletion({
  datasets: {},
  length: 3,
  typeahead: {hint: true},
  scrollable: false
 });

Dataset configuration

The datasets element within the configuration defines the columns that are returned by concierge.

One or more datasets need to be defined in order for any auto-completion to be returned.

The datasets element includes child elements corresponding to the individual data sources. Each of these contain a number of options such as the auto-completion data source, the number of suggestions, sort and grouping options and so on.

Simple auto-completion dataset

Simple auto-completion is automatically generated for a collection and is based on the words found within the index.

A single simple auto-completion source is supported.

A simple auto-completion data source is configured by adding a dataset called organic to the datasets element.

jQuery('input.query').autocompletion({
  datasets: {
   organic: {
    name: 'General suggestions',
    collection: 'main-collection',
    profile : '_default',
    show: 10
   }
  },
  length: 3
 });

The above example configures a simple auto-completion source that returns up to 10 simple suggestions from the set collection/profile. The suggestions are titled "General suggestions".

Funnelback support customisation of simple auto-completion dataset by setting correct parameters in collection.cfg for form templates.

Structured auto-completion dataset

A structured dataset is added in a similar manner to the organic dataset, except that a user defined identifier is used for the dataset.

When defining a structured dataset the following elements should be defined for each structured dataset:

  • name: the heading to use for the structured auto-completion column
  • collection: the collection that is the source for the auto-completion
  • profile: the auto-completion profile (defined within the collection above) that is the source for the auto-completion.
  • template: the template in Handlebars format used to display the suggestion. The label value is populated from the display information returned by the auto-completion web service. See: templating for further information and examples.

An example structured data source:

jQuery('input.query').autocompletion({
  datasets: {
   staff: {
    name: 'Staff members',
    collection: 'staff-members',
    profile : 'auto-completion',
    show: 10,
    template: {
      suggestion: '<div>{{label.firstName}} {{label.lastName}} ({{label.metaData.role}})<br/>{{label.summary}}</div>',
    },
   }
  },
  length: 3
 });

The above example creates a structured auto-completion column to return staff results.

The suggestions are sourced from the staff-members collection, auto-completion profile and the suggestions are templated.

Configuring multiple datasets

Defining multiple datasets is as simple as adding additional child elements to the datasets element in the configuration.

Note: the number of datasets should be limited to 3 or 4 datasets.

The following example configures concierge auto-completion returning two columns of suggestions. The first column is the simple dataset from the first example and the second column contains the staff suggestions from the structured auto-completion example.

jQuery('input.query').autocompletion({
  datasets: {
   organic: {
    name: 'General suggestions',
    collection: '${question.collection.id}',
    profile : '${question.profile}',
    show: 10
   },
   staff: {
    name: 'Staff members',
    collection: 'staff-members',
    profile : 'auto-completion',
    show: 10,
    template: {
      suggestion: '<div>{{label.firstName}} {{label.lastName}} ({{label.role}})</div>',
    }
   }
  },
  length: 3,
  typeahead: {
    hint: true
  }
 });

Example configuration

A JavaScript configuration similar to the one below could be used for the example datasets defined in the configuring a CSV data source section. This defines three columns of auto-completion for Concierge - a simple - auto completion column titled general suggestions and two columns, people and products based off the two CSV datasets.

jQuery('input.query').autocompletion({
  program   : 'http://funnelback.server/s/suggest.json',
  datasets: {
   organic: {
    name: 'General suggestions',
    collection: 'mycollection',
    profile : '_default',
    show: 10
   },
   people: {
    name: 'People',
    collection: 'mycollection',
    profile : 'people-ac',
    show: 3,
    template: {
      suggestion: '<div>{{label.firstName}} {{label.lastName}}</div>',
    }
   },
   products: {
    name: 'Products',
    collection: 'mycollection',
    profile : 'products-ac',
    show: 6,
    template: {
      suggestion: '<div><h3>{{label.product.productName}} ({{label.product.productType}})</h3><p>{{label.product.productDescription}}</p></div>',
    }
   }
  },
  length: 3,
  typeahead: {
    hint: true
  }
 });

Auto-completion plugin parameters

General settings

The following options control various aspects of the Concierge display

  • datasets: Contains the datasets configuration.
  • horizontal: Controls the layout of Concierge.
  • length: The number of characters input into a search box before suggestions are returned.
  • scrollable: Allows the height of the Concierge dropdown to be limited.
  • Typeahead: Contains custom Typeahead configuration.

Dataset settings

Dataset source settings

The following options can be used within auto-completion dataset configuration to configure the dataset, and also to adjust various aspects of the dataset behaviour:

  • alpha: Adjusts the influence of length and weighting for determining the suggestion order.
  • callback: Callback function to run before returning them to the Typeahead plugin.
  • collection: The collection from where the auto-completion dataset should be sourced.
  • default call: Configured a default action to perform for this dataset when the Concierge widget receives focus.
  • profile: The profile (within collection) where the auto-completion dataset should be sourced.
  • show: Controls how many suggestions should be returned when lookup up this dataset.
Dataset display settings

The following options can be used within auto-completion dataset configuration to adjust various aspects of the dataset display:

  • group: Controls if suggestions should be grouped within a dataset column by the CSV category field.
  • group order: Defines the order of groupings if suggestion grouping is enabled.
  • item group: Controls the name of the field used for grouping of suggestions.
  • item label: Controls the field to display in the search input after a suggestion is selected.
  • name: The value to display as the dataset heading.
  • sort: Defines the sort order for auto-completion suggestions.
  • template: Defines how the suggestion should be templated (for structured auto-completion).
  • template Merge: Controls if headers and footers are displayed for not found and pending templates.
Advanced dataset source settings

The following advanced options can be used to integrate with non-standard sources of auto-completion (such as search-based auto-completion or an external non-Funnelback auto-compeltion web-service)

  • data type: Controls the JSON format to return.
  • format: Controls the display format of the auto-completion JSON.
  • params: List of additional parameters to supply to the auto-completion program.
  • program: The web service URL to which the auto-completion request is sent.
  • query key: The parameter where the auto-completion partial query should be set.
  • query val: The value to be replaced in the URL with the partial query.
  • transform: Transformation function used to map response data returned by the auto-completion web service into the structure requried by the Concierge plugin.

Typeahead settings

Custom Typeahead settings.

  • Typeahead class names: Define custom CSS class names.
  • Typeahead highlight: Controls if suggestions include highlighting of the partial query.
  • Typeahead hint: Controls if the top suggestion should be displayed as a hint within the search box prior to selection.
  • Typeahead events: Define custom actions to perform for various Typeahead events that are triggered when interacting with Concierge.
Experimental display settings (for search-based auto-completion)

The following options are for an experimental faceted-autocompletion dataset type and should not be used at the moment:

  • Facets: Contains the configuration for faceted auto-completion.
  • Facets - blacklist: Controls which facets to ignore when producing faceted auto-completion.
  • Facets - show: Controls the number of facet categories to show per facet.
  • Facets - URL: Allows a custom URL to be prefixed to the links produced for the faceted auto-completion suggestions.
  • Facets - whitelist: If set, only the defined facets will be used for producing auto-completion.
Deprecated settings

The following deprecated settings are honoured:

See also

top

Funnelback logo
v15.12.0