Plugin: Auto-completion

Purpose

This plugin can be used to create auto-completion suggestions based on the trigger(s) provided in the collection.cfg.

Imagine you have a data source which contains staff details of a university. Once you have configured relevant metadata for the staff members' name, this plugin can create auto-completion suggestions based on the name of the staff member. So when a user comes along and starts typing "Stev" in a search box, this plugin can start suggesting staff such as "Steve" and "Steven" who both contain the letters "Stev" in their name.

Enabling the plugin

Enable the auto-completion-plugin on your results page from the Extensions screen in the administration dashboard or add the following results page configuration to enable the plugin.

plugin.auto-completion-plugin.enabled=true
plugin.auto-completion-plugin.version=2.0.1
The plugin requires the underlying data sources used to generate the auto-completion to be updated.

Plugin configuration options

The following settings must be added to the results page configuration to configure the plugin:

  • plugin.auto-completion-plugin.config.triggers: The set of fields, specified as JsonPath expressions, whose values will be used to trigger the suggestion. Fields should be separated with a comma.

  • plugin.auto-completion-plugin.config.trigger-expansion: If set to true, a user query will match words inside a multi-word trigger (ignoring stop words). This is similar to the partials mode that applies to organic auto-completion. Default: false (only match from the start of the trigger).

  • plugin.auto-completion-plugin.config.action-type: action type to perform when a suggestion is selected. Possible values are:

    • U open URL which is sourced from liveUrl field from search result data model

    • Q execute suggestion as a query (default)

  • plugin.auto-completion-plugin.config.data-sources: The data sources to gather suggestions from. By default, results will be sourced from all data sources in the search package. Possible values are a comma separated list of data source ids which are included in the search package.

    By default, a result-page contains organic spelling suggestions. If you are seeing unexpected extra suggestions after using this plugin scoped to a data-source, consider also setting the following key to blank:

    auto-completion.source=
  • plugin.auto-completion-plugin.config.display-fields: the contents of the disp object in the auto-completion response. By specifying a list of JsonPath expressions, properties from the search result will be copied across to the disp object, and hence available in the auto-completion response.

  • plugin.auto-completion-plugin.config.category: category of the suggestion which allows classifying suggestions into multiple groups. Category can be only sourced from metadata field and only first value will be used.

Configuring the trigger(s)

The main part of configuring this plugin is to set one or more appropriate triggers to compare to. Before we get into it, lets look at some terminology we’ll be using in the following examples.

Terminology

  • Partial query: what the user has typed in to a search input box so far. e.g. 'Stev'

  • Suggestion: the suggestion returned to the user as a possible auto-completion of their partial query. e.g. 'Steven'

  • Trigger: The name of the field in which to look for suggestions e.g. 'metadata.firstName'

Valid values

This plugin supports triggers specified like so:

triggers Description

/title

(Default) Suggestions will be sourced from the document title

/listMetadata/<field>

Suggestions will be sourced from the field metadata property.

/listMetadata/<field1>,/listMetadata/<field2>

Suggestions will be sourced from the field1 and field2 metadata properties.

If there’s no value specified for the trigger, or if the plugin can’t find the provided metadata then the plugin will take the title of the result object as the trigger.

Example

Given a data source with a few example records in the staff directory:

[{
    ...
    "title": "Steven Smith | Senior Lecturer",
    "url": "http://funnelback-university/staff/123",
    "listMetadata": {
        "firstName": ["Steven"],
        "lastName": ["Smith"]
    },
    ...
}, {
    ...
    "title": "Steve Wonder | Fellow",
    "url": "http://funnelback-university/staff/456",
    "listMetadata": {
        "firstName": ["Steve"],
        "lastName": ["Wonder"]
    },
    ...
}, {
    ...
    "title": "Jane Doe | Dean",
    "url": "http://funnelback-university/staff/789",
    "listMetadata": {
        "firstName": ["Jane"],
        "lastName": ["Doe"]
    },
    ...
}]

If the plugin was configured with:

plugin.auto-completion-plugin.config.triggers=/listMetadata/firstName

When a user starts searching for "Stev", this plugin will compare "Stev" against ["Steve", "Jane", "Steven"] and offer "Steve" and "Steven" as suggested query completions.

If the plugin was configured with:

plugin.auto-completion-plugin.config.triggers=/listMetadata/firstName,/listMetadata/lastName

this plugin will compare "Stev" against ["Steven", "Smith", "Steve", "Wonder", "Jane", "Doe" ].

If the plugin was configured with:

plugin.auto-completion-plugin.config.triggers=title

The suggestions might be: "Steven Smith Senior Lecturer" and "Steve Wonder Fellow"

Configuring trigger expansion

The plugin is able to expand a single trigger into multiple 'partial' triggers by stripping words from the beginning of the trigger.

For example:

Funnelback Search Engine becomes Funnelback Search Engine, Search Engine, Engine

When the trigger contains very common English words (aka stop words) these will be skipped rather than being used to begin a trigger, to, for example, avoid the issue of thousands of triggers beginning with 'and'.

This mode is not enabled by default. To enable this mode, set the following config setting in the results page containing the plugin:

plugin.auto-completion-plugin.config.trigger-expansion=true

Configuring the contents of the disp property (the display fields)

By default, the suggestion endpoint disp property contains a plain text string that matches the trigger value.

To get a Json object with more details about the suggestion match, specify a list of JsonPath expressions in the display-fields configuration setting. Search result values that match the JsonPath values will be copied across to the disp object, with expressions that don’t match silently dropped.

For example, to return the title, url, and listMetadata.lastName values, you would specify:

plugin.auto-completion-plugin.config.display-fields=/title, /url, /listMetadata/lastName

For the first search result from the example above, this will result in a disp object like so:

{
    "title": "Steven Smith | Senior Lecturer",
    "url": "http://funnelback-university/staff/123",
    "listMetadata": {
        "lastName": ["Smith"]
    }
}

If fields that don’t exist are specified, they are not returned in the disp result; so

plugin.auto-completion-plugin.config.display-fields=/title, /foo, /listMetadata/lastName, /listMetadata/foobar

results in

{
    "title": "Steven Smith | Senior Lecturer",
    "listMetadata": {
        "lastName": ["Smith"]
    }
}

Upgrade Notes

Upgrading to version [2.0.0]

In version 2.0.0, the plugin config setting for triggers was renamed from plugin.auto-completion-plugin.config.trigger to plugin.auto-completion-plugin.config.triggers. To upgrade to version 2.0.0, the config key plugin.auto-completion-plugin.config.trigger needs to be changed to plugin.auto-completion-plugin.config.triggers in all results page config files where it is present.

Changelog

[2.0.1]

Added

  • plugin.auto-completion-plugin.config.category configuration key to set category field

[2.0.0]

Added

  • plugin.auto-completion-plugin.config.data-sources configuration key to scope suggestions from particular data sources

Changed

  • Configuration key to set triggers (see upgrade notes)

[1.0.0]

Added

  • plugin.auto-completion-plugin.config.trigger configuration key to set suggestion trigger

  • plugin.auto-completion-plugin.config.action-type configuration key to define action to execute on selecting suggestion

  • plugin.auto-completion-plugin.config.display-fields configuration key to define list of fields to return with suggestion to customise suggestion display

© 2015- Squiz Pty Ltd