Search API Autocomplete

Information for developers

Adding autocomplete to custom search forms

With Search API Autocomplete, adding autocomplete functionality to your own custom search form is fairly simple. These are the basic steps:

• In your custom module, implement hook_search_api_autocomplete_types() to define a new type of search. Documentation for this hook is in the search_api_autocomplete.api.php file, but it should look something like this:
  

  function MODULE_search_api_autocomplete_types() {
    $types['MODULE'] = array(
      'name' => t('MODULE searches'),
      'description' => t('Searches provided by the <em>MODULE</em> module.'),
      'list searches' => 'MODULE_list_autocomplete_searches',
      'create query' => 'MODULE_create_autocomplete_query',
      // OPTIONAL – only if you want additional search-specific options, like for Views:
      'config form' => 'MODULE_autocomplete_config_form',
    );
  
    return $types;
  }
  

• Then you of course need to implement the two (or three) callbacks. Take a look at search_api_autocomplete.search_api_page.inc for examples. These are the two required functions:
  

  function MODULE_list_autocomplete_searches(SearchApiIndex $index) {
    $ret = array();
    // If your module only provides one search, it's simple:
    $ret['MODULE']['name'] = t('MODULE search');
    // Otherwise, loop over all defined searches:
    foreach (… as $search) {
      // Remember to use a proper prefix to avoid conflicts.
      $id = 'MODULE_' . $search->id;
      $ret[$id]['name'] = $search->label;
      // If the searches have additional options/information:
      $ret[$id]['options']['custom'] = $search->options;
    }
    return $ret;
  }
  
  function MODULE_create_autocomplete_query(SearchApiAutocompleteSearch $search, $complete, $incomplete) {
    // Create a search query just like you do in the custom search submit function.
    // If you have this in a separate function, all the better!
    $query = MODULE_create_query($search->options['custom']);
    $query->keys($complete);
    return $query;
  }
  

• Then you have to add autocompletion into the form builder function:
  

  function MODULE_search_form(array $form, array &$form_state) {
    // …
    $form['keys'] = array(
      '#type' => 'textfield',
      '#title' => t('Enter keywords'),
    );
    // If there's only one search in your module, with ID "MODULE".
    // Otherwise, get the proper ID, as assigned in MODULE_list_autocomplete_searches(),
    // for the current search.
    $autocomplete_id = 'MODULE';
    $search = search_api_autocomplete_search_load($autocomplete_id);
    if ($search && $search->enabled) {
      $search->alterElement($form['keys']);
    }
    // …
    return $form;
  }
  

• Your custom search will now appear in the search api admin panel where you have to enable autocomplete and that's it. Your custom search api form will now be autocompleting like crazy!