Providing search plugins

Last updated on
29 September 2017

Search plugins are used to identify search forms for which autocompletion can be added. All known plugins for a certain index will be displayed on that index's "Autocomplete" tab. A search entity can then be created based on each of these plugins. (At most one entity can be created per plugin.) Therefore, if your module provides a search form, or you wish to add Autocomplete support to another module's search form, you need to provide a search plugin for that form. (In cases where several search forms can be created with the same mechanism, a plugin deriver can/should be used to create one plugin (derivative) for each form created that way.)

Search plugins use the normal Drupal 8 Plugin API, so defining new ones should be pretty simple for anyone familiar with it.

Key information

Plugin base class: \Drupal\search_api_autocomplete\Search\SearchPluginBase
Plugin namespace: Drupal\[MODULE]\Plugin\search_api_autocomplete\search
Annotation: @SearchApiAutocompleteSearch
Service ID: plugin.manager.search_api_autocomplete.search

Other necessary code

While a search plugin encapsulates most information about a search form that the Search API Autocomplete module needs, the module cannot use those plugins to automatically alter the search forms as appropriate (since there are too many variables involved). Therefore, in addition to providing the plugin definition, you will also need to add a form alter hook that will alter the search form in question.

In the hook implementation, you'll have to determine the plugin ID matching the given form and then do something like this:

  $search = \Drupal::entityTypeManager()
    ->getStorage('search_api_autocomplete_search')
    ->loadBySearchPlugin($search_plugin_id);

  if ($search && $search->status()) {
    \Drupal::getContainer()
      ->get('search_api_autocomplete.helper')
      ->alterElement($form[$element_key], $search);
  }

Depending on the specific scenario, the code might of course be more complicated than that.

For examples, see the search_api_autocomplete_form_views_exposed_form_alter() and search_api_autocomplete_form_search_api_page_block_form_alter() form alter hook implementations in the search_api_autocomplete.module file.

Important methods

The central (and, more or less, only relevant) method of a search plugin is the createQuery() method. Its purpose to create a search query object, based on search keywords entered by the user, that should be as close as possible to the query that would be created when submitting the associated search form with these keys.

Optionally, you can also implement \Drupal\Core\Plugin\PluginFormInterface in your search plugin class to provide a configuration form for users. In this case, you might want to use \Drupal\search_api\Plugin\PluginFormTrait to avoid some boilerplate code.
When the plugin can have configuration (even if no form is provided for it), defaultConfiguration() should also be implemented so that default settings can be applied correctly.

Help improve this page

Page status: No known problems

You can: