Autocomplete API

Website personalisation: JavaScript integration

Ometria onsite's autocomplete function provides exceptionally fast predictive type-ahead text, helping site visitors find the right product search terms.

Reference

Here is a list of parameters available in the autocomplete API:

<script>
$g.autocomplete({
    format              : "{{ html_or_json }}", // optional (String), default: "html"
    input_selector      : "{{ input_selector }}", // required (String)
    dropdown_selector   : "{{ dropdown_selector }}" // optional (String),
    page_context        : { /* parameters */ }, // optional (Object),
    args                : { /* parameters */ }, // optional (Object or Function),
    position            : function() { /* custom actions */ } // optional (Function),
    before_load         : function() { /* custom actions */ } // optional (Function),
    after_load          : function() { /* custom actions */ } // optional (Function),
    show                : function() { /* custom actions */ } // optional (Function),
    hide                : function() { /* custom actions */ } // optional (Function)
});
</script>

Parameter

Required?

Type

Description

format

Optional

String

A string defining the format of the content returned.

The allowed values are html or json.

If format is not specified then a default value of html is used.

input_selector

Required

String

A string containing a CSS selector.

This property identifies the search input that Autocomplete will bind to.

dropdown_selector

Required

String

A string containing a CSS selector.

This property identifies the output in which autocomplete will publish results.

page_context

Optional

Object

An object defining various details about the current page.

These include:

  • category_id (Optional): Only required if you want to make the autocomplete category specific.
  • language_id (Optional): Only required if multiple languages are defined.
  • currency_id (Optional): Only required if multiple currencies are defined.

args

Optional

Object/Function

An object or function defining custom parameters.

These custom parameters are typically dynamic pieces of information that can be used as triggers in Ometria's onsite feature.

position

Optional

Function

A callback function which can be used to override the default behaviour for the positioning of the autocomplete popup.

The default behaviour is to position the autocomplete popup close to the search input.

before_load

Optional

Function

A callback function which is called just after every autocomplete request.

after_load

Optional

Function

A callback function which is called just after every autocomplete request.

show

Optional

Function

A callback function which can be used to override the default behaviour for making the autocomplete popup visible.

The default behaviour is to set the autocomplete style property to "block".

hide

Optional

Function

A callback function which can be used to override the default behaviour for making the autocomplete popup hidden.

The default behaviour is to set the autocomplete style property to "none".

Examples

Simple integration

Here is a standard implementation.

All you need to do is to create an html element to contain the results and then tell the API about it:

<-- html input -->
<input id="Search" />
<-- create an element to contain autocomplete results -->
<div id="Autocomplete"><-- Ometria will add content here --></div>
<script>
$g.autocomplete({
   input_selector          : "#Search",
   dropdown_selector       : "#Autocomplete"
});
</script>

Page context / Args

In this example, additional information is being sent in the page_context and args objects:

<-- html input -->
<input id="Search" />
<-- create an element to contain autocomplete results -->
<div id="Autocomplete"><-- Ometria will add content here --></div>
<script>
$g.autocomplete({
   input_selector          : "#Search",
   dropdown_selector       : "#Autocomplete",
   page_context            : { currency_id: "USD", language_id: "en-us" },
   args                    : { geo_country: "US", geo_state: "AK", weather: "snowing" }
});
</script>

Positioning

In this example the default positioning behaviour is overridden.

If the position of the autocomplete popup is being controlled by CSS, create an empty function so that no default positioning is applied by the code.

<-- html input -->
<input id="Search" />
<-- create an element to contain autocomplete results -->
<div id="Autocomplete"><-- Ometria will add content here --></div>
<script>
$g.autocomplete({
   input_selector          : "#Search",
   dropdown_selector       : "#Autocomplete",
   position                : function() {}
});
</script>

Custom hooks

In this example, various custom hooks are being applied to some common use cases:

<-- html input -->
<input id="Search" />

<-- create an element to contain autocomplete results -->
<div id="Autocomplete"><-- Ometria will add content here --></div>
<script>
$g.autocomplete({
   input_selector          : "#Search",
   dropdown_selector       : "#Autocomplete",
   before_load             : function() {
       // show content loading
       document.querySelector("#Autocomplete").innerHTML = "Loading, please wait...";
   },
   after_load              : function() {
       // wire in some custom events, for example load 3rd party reviews
   },
   show                    : function() {
       // override default behaviour
       document.querySelector("#Autocomplete").classList.add("my-class");
   },
   hide                    : function() {
       // override default behaviour
   document.querySelector("#Autocomplete").classList.remove("my-class");
   }
});
</script>