Help Center

Menu

Plugin: auto-completion-plugin

Other versions of this plugin may exist. Please ensure you are viewing the documentation for the version that you are currently using. If you are not running the latest version of your plugin we recommend upgrading. See: list of all available versions of this plugin.

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

Add the following to profile.cfg to enable the plugin.

plugin.auto-completion-plugin.enabled=true
plugin.auto-completion-plugin.version=2.0.0

In addition to enabling the plugin above, you can configure:

  • where suggestions are sourced from, using one or more comma separated JsonPath expressions. By default it’s the /title field from search result data model

    plugin.auto-completion-plugin.config.triggers=<where to source trigger values from as JsonPath>
    plugin.auto-completion-plugin.config.triggers=/title
    plugin.auto-completion-plugin.config.triggers=/title,/summary

  • action type to perform when 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.action-type=U

  • which data sources to gather suggestions from. By default, results will be sourced from all data sources in the search package. Possible values should be a comma separated list of data source ids which are also part of the search packages' meta.components.

    plugin.auto-completion-plugin.config.data-sources=client~ds-staff, client~ds-customers
Warning: 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=

  • 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.display-fields=/title,/listMetadata/firstName

Note, once you enable this plugin or change the above trigger, you need to re-index your data source in order for the auto completion suggestions to be generated.

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 query completion suggested 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 collection 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.

All versions of auto-completion-plugin