Help Center

Menu

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.

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-2.6.0.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/thirdparty/typeahead-0.11.1/typeahead.bundle.min.js"></script>
<script type="text/javascript" src="http://funnelback.server/s/resources-global/thirdparty/handlebars-4.7/handlebars.min.js"></script>
<script type="text/javascript" src="http://funnelback.server/s/resources-global/js/funnelback.autocompletion-2.6.0.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 widget

The Concierge auto-completion widget 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 data sets, 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 data set

  • 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 data set, 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
 });

Data set configuration

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

One or more data sets 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 data set

Simple auto-completion is automatically generated for a results page 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 data set called organic to the data sets 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 supports customization of the simple auto-completion data set by setting correct parameters in the results page configuration for FreeMarker templates.

Structured auto-completion data set

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

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

  • 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 data sets

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

the number of data sets should be limited to 3 or 4 as each additional data set will result in another web service call and reduce the performance of the auto-completion. The widget UI’s horizontal layout also doesn’t work with more than about 3 or 4 data sets before the layout becomes problematic.

The following example configures concierge auto-completion returning two columns of suggestions. The first column is the simple data set 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 data sets 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 data sets.

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 widget parameters

General settings

The following options control various aspects of the Concierge display

  • datasets: Contains the data sets configuration.

  • debounceDelay: Define the delay in milliseconds before requesting suggestions.

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

Data set settings

Data set source settings

The following options can be used within auto-completion data set configuration to configure the data set, and also to adjust various aspects of the data set 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 data set should be sourced.

  • default call: Configured a default action to perform for this data set when the Concierge widget receives focus.

  • profile: The profile (within collection) where the auto-completion data set should be sourced.

  • show: Controls how many suggestions should be returned when lookup up this data set.

Data set display settings

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

  • group: Controls if suggestions should be grouped within a data set 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 data set 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 data set 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-completion 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 required by the Concierge widget.

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 data set 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