Semantic Autocomplete

Overview

The semantic autocomplete (formerly known as "semantic autocompleter") is a semantic-based query prediction that uses the API to search for results. It provides better results than the normal typeahead autocomplete because it uses semantic search instead of keywords, but it is slightly slower.

This component automatically creates a new store for itself.

Usage

This is how you create this component:

sdk.component('semantic-autocompleter', target: HTMLElement|String, options: Object);

Sample

By default, this component looks like this:

(Note how the second result title features speaking, which is semantically related to the search input talking. This is how the semantic autocomplete differs from the typeahead autocomplete.)

Options

The following options can be set in this component:

Name Type Default Description
resultsPerPage Number 10 The number of results to display
debounceTime Number 2000 The results are refreshed when users stop typing for the specified debounceTime time (in milliseconds).
triggers Array ['.', ',', ':', ';', '(', ')', '¿', '?', '¡', '!', ' '] The results are refreshed when users type one of the specified texts in triggers.
transformData Function (object) => object Function to transform the object passed to the view
baseUrl String "" URL to add to all of the result links
templates Object The templates to override the default render behavior
templates.item String | (Object) => String Template to use for each result. This template will receive an object containing the result. See here for additional details.
templates.header String | () => String Header template
templates.footer String | () => String Footer template
searchParams Object { matchHighlightTags: ['<strong class="inbenta-match">', '</strong>'], correctionHighlightTags: ['<em class="inbenta-correction">', '</em>'], expansionHighlightTags: ['<em class="inbenta-expansion">', '</em>'] } The API parameters to send in every request. For the format to use, see the /federated-search endpoint of Search API Routes.
Note: API parameters facets and attributes cannot be modified this way. See here for additional details.
placement String bottom-start The popup placement. See popper.js placements docs for valid values. This option only works if behaveAsPopover parameter is set to true.
modifiers Object bottom-start The popup modifiers. See popper.js placements docs for valid values. This option only works if behaveAsPopover parameter is set to true.
behaveAsPopover Boolean false If set to true, the Autocomplete behaves as a popover. This means that the results container floats over the other page elements. This feature uses the popper library. Inbenta recommends that you set this option to true.
Note about searchParams

You can use the searchParams component option to modify the API search queries. However, some API attributes can be also handled by other linked components. This means that even if you set some searchParams, they may not apply if you are also using certain components.

These are the components that may affect this option:

Component Affected API attributes
Results offset, length
Refinement tabs attribute, sort
Refinement list attribute, sort
Results per page offset, length
Router filters, query, offset
Semantic autocomplete query, offset, length
Sort by selector sort

Properties

Property Description
suggestion Get the current active content

Methods

The following methods can be used with this component:

Name Description
setInputElement(input: HTMLInputElement) Listen to the given input element to automate certain actions:
- Show the autocomplete results when focused.
- Navigate the autocomplete results with the vertical arrow keys.
trackClick(content: Object) Track a click to the given content

Tracking

This component calls the API to do the following:

  • every time a search is performed, it sends a /federated-searches request with the type parameter set to instant and tracking set to true, to get the result of the question and track the search as a instant_search event.
  • it triggers the instant_click event when a user clicks on a content.

Events

Events to listen on this component:

Name (data key) Description
click When a user clicks on a suggestion from the autocomplete, it triggers a click event.

Templates

Item Template

The item template receives a result enhanced with additional parameters. It uses this format:

{
  id: 1,
  title: "Example content",
  highlightedTitle: ”<strong>Example</strong> content”
  attributes: {
    URL: ["/contents/1"],
    PARAGRAPHS: ["Paragraph 1"],
    // Any other attribute
  creationDate: "20190916162709",
  modificationDate: "20190916164248",
  score: 0.5
  },
  // Use this to render the absolute content URL.
  __url: "https://test.io/contents/1",
  // Render this into an HTML element to track click events.
  __clickable: "...",
  // Whether the result is currently focused or not.
  __focused: true,
  // Index of the suggestion
  __hitIndex: 0
}

Examples

Usage with SearchBox component
<div id="search-box"></div>
<div id="semantic-autocompleter"></div>

<script>
    var searchBox = sdk.component('search-box', '#search-box');

    var semanticAutocompleter = sdk.component('semantic-autocompleter', '#semantic-autocompleter');
    semanticAutocompleter.setInputElement(searchBox.getInputElement());
</script>
Using templates
<div id="search-box"></div>
<div id="semantic-autocompleter"></div>

<script>
    var searchBox = sdk.component('search-box', '#search-box');

    var semanticAutocompleter = sdk.component('semantic-autocompleter', '#semantic-autocompleter', {
        templates: {
            item: '<a'
                + ' class="{{#__focused}}active{{/__focused}}"'
                + ' href="{{ __url }}"'
                + ' target="_blank"'
                + ' {{{ __clickable }}}>'
                + '     {{{ highlightedTitle }}}'
                + '</a>',
        },
    });
    semanticAutocompleter.setInputElement(searchBox.getInputElement());
</script>
Automatically search on input change
<input type="text" id="query">

<div id="semantic-autocompleter"></div>

<script>
    // The input will trigger whether its value is changed.
    var input = document.querySelector('#query');

    var semanticAutocompleter = sdk.component('semantic-autocompleter', '#semantic-autocompleter');
    semanticAutocompleter.setInputElement(input);
</script>
Use refinements and trigger custom searches
<div id="semantic-autocompleter"></div>

<script>
  var semanticAutocompleter = sdk.component('semantic-autocompleter', '#semantic-autocompleter');
  semanticAutocompleter.searchStore.query = 'cars';
  semanticAutocompleter.searchStore.addFacet('color');
  semanticAutocompleter.searchStore.addFacetRefinement('color', 'blue');
</script>