Front-end Custom Events

Autocomplete menu events

You can adjust all the logic of the autocomplete.js integration by registering a custom method in your JS file. Registering of a hook can be done by using algolia JS object.

You can learn how to add a custom JS file in a Create a custom extension tutorial.

Possible hooks:

• beforeAutocompleteSources(sources, algoliaClient, algoliaBundle)
  • can be used to modify default data sources
  • the hook must return sources variable
• beforeAutocompleteOptions(options)
  • can be used to modify default options of autocomplete menu
  • the hook must return options variable

These hooks are triggered right before the autocomplete feature initializes.

Example of the hooks:

1
2
3
4
5
6
7
8
9
algolia.registerHook('beforeAutocompleteSources', function(sources, algoliaClient, algoliaBundle)  {
  // Add or modify sources, then return them
  return sources;
});

algolia.registerHook('beforeAutocompleteOptions', function(options) {
  // Modify options, then return them
  return options;
});

• afterAutocompleteStart(algoliaAutocompleteInstance)
  • can be used to observe events on the autocomplete element
  • the hook must return algoliaAutocompleteInstance variable

Example of the hook:

1
2
3
4
5
// Bind new event on the autocomplete element
algolia.registerHook('afterAutocompleteStart', function(algoliaAutocompleteInstance) {
  // Modify default autocomplete instance, then return it
  return algoliaAutocompleteInstance;
});

Instant search page events

You can adjust all the logic of the InstantSearch.js integration by registering a couple of custom hooks:

• beforeInstantsearchInit(instantsearchOptions, algoliaBundle)
  • can be used to modify default instantsearch options
• beforeWidgetInitialization(allWidgetConfiguration, algoliaBundle)
  • can be used to add/remove/modify any widget(s)
• beforeInstantsearchStart(search, algoliaBundle)
  • can be used to modify the instantsearch instance before call of start() method
• afterInstantsearchStart(search, algoliaBundle)
  • can be used to modify the instantsearch instance after call of start() method

By registering these hook(s) in your JavaScript file, you can directly modify their parameters which must be returned back from the method.

Example of the beforeInstantsearchInit(instantsearchOptions, algoliaBundle) hook:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// Modify default `instantsearchOptions`
algolia.registerHook('beforeInstantsearchInit', function(instantsearchOptions, algoliaBundle) {

  // Adding a custom Query Rule context
  var newQueryRuleContext = 'new-custom-query-rule-context';
  instantsearchOptions.searchParameters.ruleContexts.push(newQueryRuleContext);

  // Example of an after search callback
  var callbackSearchFunction = instantsearchOptions.searchFunction;
  instantsearchOptions.searchFunction = function(helper) {

    // Add your `searchFunction` methods here

    // Run the previous `searchFunction`
    callbackSearchFunction(helper);
  }

  return instantsearchOptions;
});

Example on how to add a new toggleRefinement widget to instant search page:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
algolia.registerHook('beforeWidgetInitialization', function(allWidgetConfiguration) {
  const wrapper = document.getElementById('instant-search-facets-container');

  const widgetConfig = {
    container: wrapper.appendChild(createISWidgetContainer('in_stock')),
    attributeName: 'in_stock',
    label: 'In Stock',
    values: {
      on: 1
    },
    templates: {
      header: '<div class="name">Is in stock</div>'
    }
  };

  if (typeof allWidgetConfiguration['toggle'] === 'undefined') {
    allWidgetConfiguration['toggle'] = [widgetConfig];
  } else {
    allWidgetConfiguration['toggle'].push(widgetConfig);
  }

  return allWidgetConfiguration;
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
algolia.registerHook('beforeWidgetInitialization', function(allWidgetConfiguration) {
  const wrapper = document.getElementById('instant-search-facets-container');

  const widgetConfig = {
    container: wrapper.appendChild(createISWidgetContainer('in_stock')),
    attribute: 'in_stock',
    on: 1,
    templates: {
      label: 'In Stock'
    }
  };

  if (typeof allWidgetConfiguration['toggleRefinement'] === 'undefined') {
    allWidgetConfiguration['toggleRefinement'] = [widgetConfig];
  } else {
    allWidgetConfiguration['toggleRefinement'].push(widgetConfig);
  }

  return allWidgetConfiguration;
});

All default widgets can be found in allWidgetConfiguration object and can be removed or modified in this method.