README.txt in Search API Autocomplete 8

Search API Autocomplete
-----------------------

Adds autocomplete capabilities for Search API searches.


Information for users
---------------------

- Necessary server feature

The default "Retrieve from server" suggester provided by this module retrieves
autocomplete suggestions from the server, based on the indexed data. For this to
work, the server has to support the "search_api_autocomplete" feature. Having
autocompletion for indexes on servers for which the backend doesn't support this
feature is only possible if you use a different suggester (like "Display live
results", or one provided by a separate module).
Currently, the Solr backend [1] and the Database backend (included in the Search
API project) are known to support this feature.

[1] https://www.drupal.org/project/search_api_solr

- Necessary setup

After having installed and enabled the module, you have to do some
administrative steps to activate the autocomplete functionality. Autocompletion
can be enabled and configured for each search separately.

To activate autocompletion for an index's searches, go to the index's
„Autocomplete“ tab. There, you see all available searches for the index and can
enable (and afterwards configure) autocompletion for each of them. All fulltext
key fields on the searches should then become autocompletion fields.

There is an autocomplete permission for each separate search. Therefore, after
adding autocomplete to a new search, don't forget to set the appropriate
permissions.

- Supported searches

Currently, only search forms built by the Search API Pages or Views modules are
supported directly. However, other modules can easily also use this
functionality. See the "Information for developers" below for details.

- Hidden settings

search_api_autocomplete.settings:enable_custom_scripts:
  Enables the "Use custom script" suggester which lets you redirect the
  autocomplete AJAX request to a path or URL of your choosing. Since this is
  mostly interesting for developers, who want to write their own autocomplete
  code (possibly bypassing Drupal for performance reasons), this suggester is
  not available otherwise by default. (Setting defaults to FALSE, set to TRUE to
  make the suggester available.)


Information for developers
--------------------------

- Supporting a new method of creating suggestions

You can add your own implementation for creating autocomplete suggestions by
creating a so-called "suggester" plugin. For details, see the interface
documentation in src/Suggester/SuggesterPluginBase.php.

- Supporting autocompletion with a backend plugin

To support autocompletion with a backend plugin, the plugin has to support the
"search_api_autocomplete" feature. This will necessitate the backend class to
have a getAutocompleteSuggestions() method as detailed in the interface in
src/AutocompleteBackendInterface.php.

- Supporting autocompletion on a search form

If you have a search form not generated by the Search views or Search pages
modules, you can add an autocomplete search plugin to support autocompletion for
it. See src/Search/SearchPluginBase.php for the plugin type documentation,
or src/Plugin/search_api_autocomplete/search/ for examples. Additionally, you
will need to write a form alter hook to adapt your search form's input element.
For examples, see search_api_autocomplete_form_views_exposed_form_alter() or
search_api_autocomplete_form_search_api_page_block_form_alter().