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 theresult.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
andsummary
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 fromliveUrl
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 metadatafirstName
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 triggersProctor Leopold Smith
,Leopold Smith
andSmith
. -
false
: (default) Only generate a single trigger value. e.g. for a value ofJohn Proctor Leopold Smith
only trigger the suggestion when someone starts typingjoh
.
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 |
---|---|
|
(Default) Suggestions will be sourced from the document title |
|
Suggestions will be sourced from the |
|
Suggestions will be sourced from the |
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.0]
[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.