Help Center

Menu

Plugin: Auto-completion

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.

Purpose

This plugin generates a structured auto-completion source from the search index.

Usage

Enabling the plugin

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

plugin.auto-completion-plugin.enabled=true
plugin.auto-completion-plugin.version=2.0.3
The plugin requires a re-index for the changes to take effect.

Plugin configuration settings

The following options can be set in the results page configuration:

  • plugin.auto-completion-plugin.config.triggers: A comma-delimited list of fields in JsonPath format from where auto-completion triggers are sourced. The values contained within these fields will be used as the trigger values. The JsonPaths are applied to the search result element (/title corresponds to the result.title element from the search data model for an individual search result).

    Default: use a single trigger sourced from the /title field.

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

    Example: use the title and summary fields as triggers.

      plugin.auto-completion-plugin.config.triggers=/title,/summary

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

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

    • Q execute suggestion as a query (default).

    e.g. Go to a URL when the suggestion is clicked.

    +

      plugin.auto-completion-plugin.config.action-type=U

  • plugin.auto-completion-plugin.config.data-source: Comma separated list of data source IDs from where suggestions are sourced. By default, results will be sourced from all data sources included in the results page. Acceptable values are a subset of these data source IDs.

      plugin.auto-completion-plugin.config.data-sources=client~ds-staff, client~ds-customers

  • plugin.auto-completion-plugin.config.display-fields: Comma separated list of result fields (expressed using JsonPaths) to return in the display object.

    e.g. Include title and metadata firstName elements:

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

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

      plugin.auto-completion-plugin.config.category=/listMetadata/METADATA_CLASS_NAME

    e.g. Source the category from the category metadata field.

      plugin.auto-completion-plugin.config.category=/listMetadata/category

  • plugin.auto-completion-plugin.config.trigger-expansion=true: Generate partial matching triggers. Possible values are:

    • true: generate extra triggers that will allow a user’s query to match the start of a word inside a multi-word trigger. This provides similar behaviour to the -partials mode for simple auto-completion. e.g. For a trigger value, John Proctor Leopold Smith trigger, generate extra triggers Proctor Leopold Smith, Leopold Smith and Smith.

    • false: (default) Only generate a single trigger value. e.g. for a value of John Proctor Leopold Smith only trigger the suggestion when someone starts typing joh.

    Triggers starting with a stop word (such as and or the) will be skipped.

  • auto-completion.source: This is a standard results page option that controls the sources of auto-completion when the auto-completion indexes are generated. By default, auto-completion generated on a result-page contains organic spelling suggestions. Set the following to suppress the organic suggestions:

      auto-completion.source=

Details

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 using JsonPath expressions, which are compared to an individual results taken from the search result data model:

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 results page 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 auto-completion suggestions.

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 for Stev would 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 the following disp object:

{
    "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. e.g.

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.

Change log

[2.0.3]

Changed

  • Upgraded jackson-datatype-guava dependency from v2.10.3 to 2.12.5

  • Use Java native isBlank method as in Jsoup v1.12.1 class org.jsoup.helper.StringUtil was moved and marked for internal use only.

[2.0.2]

Added

  • Summary field will show full data

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

See also

All versions of auto-completion-plugin