AutoSuggest elements

An AutoSuggestFormElement writes a <div> tag to the output containing all markup for an autoSuggest control.

Element and builder

The AutoSuggestFormElement has an equivalent AutoSuggestFormElementBuilder. A builder can be created using BootstrapUiBuilders.autosuggest() factory methods.

By default, the autosuggest form element expects an id and a value property on the fetched results. The id is the reference to the domain object, and the value is the value that is displayed by default.

AutoSuggestFormElementConfiguration

The autosuggest control takes in an AutoSuggestFormElementConfiguration to configure a datasets and has the following options:

Method Description

Method	Description
`withDataSet`	Configure the dataset with the given name, if it is not yet present, it will be added first.
`showHint`	Should the textbox show a hint for auto-completion.
`highlight`	Highlight the matching input text in the suggestions.
`minLength`	Minimum length the input value should have before fetching suggestion.

withDataSet

Configure the dataset with the given name, if it is not yet present, it will be added first.

showHint

Should the textbox show a hint for auto-completion.

highlight

Highlight the matching input text in the suggestions.

minLength

Minimum length the input value should have before fetching suggestion.

Example of a simple autosuggest configuration

BootstrapUiBuilders
    .autosuggest()
    .configuration(
            AutoSuggestFormElementConfiguration.withDataSet( (1)
                    dataSet -> dataSet.remoteUrl( "/bootstrapAutosuggest/suggest?query={{query}}" )
            ).minLength( 2 )
    )
    .build()

1	configure a dataset which fetches data from an url, once at least 2 characters are present

Given the above configuration, the following markup would be rendered:

<div data-bootstrapui-adapter-type="autosuggest" class="axbum-typeahead"
    data-bootstrapui-autosuggest="{&quot;highlight&quot;:true,&quot;hint&quot;:true,&quot;minLength&quot;:1,&quot;_datasets&quot;:[{&quot;name&quot;:&quot;default&quot;,&quot;bloodhound&quot;:{&quot;remote&quot;:{&quot;url&quot;:&quot;/bootstrapAutosuggest/suggest?query={{query}}&quot;}}}]}">
    <input autocomplete="off" type="search" class="js-typeahead form-control"></input>
    <input type="hidden" class="js-typeahead-value"></input>
</div>

Configuring templates

An AutoSuggestFormElementBuilder supports configuring templates by specifying a ViewElementBuilder for the given template. Depending on the configuration, different objects are available within the context of the template. These can be specified with curly braces, for example {{query}}, within the template and will be interpolated when the element is rendered.

The following templates can be configured:

Template name Description

Template name	Description
header	Rendered at the top of the dataset when suggestions are present. In the rendering context, the `query` and the `suggestions` will be available.
footer	Rendered at the top of the dataset when suggestions are present. In the rendering context, the `query` and the `suggestions` will be available.
pending	Rendered when there are no synchronous suggestions available, but asynchronous suggestions are being fetched. In the rendering context the `query` will be available.
suggestion	Used to render a single suggestion. The associated suggestion object will be available in the context. If no template is configured, the default template `<div>{{value}}</div>` will be used.
notFound	Rendered when no suggestions could be found for the current query. In the rendering context the `query` will be available.

header

Rendered at the top of the dataset when suggestions are present. In the rendering context, the query and the suggestions will be available.

footer

Rendered at the top of the dataset when suggestions are present. In the rendering context, the query and the suggestions will be available.

pending

Rendered when there are no synchronous suggestions available, but asynchronous suggestions are being fetched. In the rendering context the query will be available.

suggestion

Used to render a single suggestion. The associated suggestion object will be available in the context. If no template is configured, the default template <div>{{value}}</div> will be used.

notFound

Rendered when no suggestions could be found for the current query. In the rendering context the query will be available.

When configuring a template, optionally a dataset id can be specified for which the template should be added.

Configuring a template

BootstrapUiBuilders
    .autosuggest()
    .notFoundTemplate( BootstrapUiBuilders.div().css( "autosuggest-not-found" )
                                          .add( BootstrapUiBuilders.text( "There are no results available for '{{query}}'" ) ) )
    .build();

Given the query 'John', the following markup would be rendered in the suggestions dropdown if there are no results:

<div class="autosuggest-not-found">There are no results available for 'John'</div>

Configuring a template for a dataset

BootstrapUiBuilders
    .autosuggest()
    .notFoundTemplate( "people", BootstrapUiBuilders.text("No results found") )
    .build();

Dynamic configuration of a dataset

An autosuggest form element supports clientside modification of the active dataset(s). On the autosuggest element itself an attribute datasets is available which holds the configured Bloodhound search engines. By accessing the datasets, the urls used to fetch the data can be modified:

$( '[data-bootstrapui-adapter-type="autosuggest"]' ) (1)
    .data( 'datasets' )['default'].remote.url = '/active-users'; (2)

1	Select the autosuggest for which you want to modify a dataset. In this case, we’re selecting an autosuggest form element by its corresponding control adapter.
2	Find the dataset by name and reconfigure the remote url. Now the new url will be used when data is fetched.

« Form controls AutoSuggest Checkbox »