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 (possibly 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 search pages or search views are
supported directly. However, other modules can easily also use this
functionality. See the "Information for developers" below for details.

  - Caution! -
  If your view uses contextual filters, those can generally not be inferred in
  the autocompletion function which might lead to problems of different kinds,
  including display of confidential information (if such information would be
  available without contextual filters), wrong suggestions or complete absence
  of suggestions.
  Therefore, you should create another display without contextual filters, if
  necessary, and make sure that this doesn't lead to any leaks.
  If you want to fix this in a custom way for your site, take a look at
  example_search_api_query_alter() for suggestions.

- Hidden settings

search_api_autocomplete.settings:delay:
  Change the delay before the autocomplete request is sent when a user is typing
  into an autocomplete field. The setting is only effective on pages with Search
  API Autocomplete forms, not on other pages with autocomplete fields. The unit
  of the value is milliseconds, the default is 300.

search_api_autocomplete.settings:scripts:
  Allows you to override the autocomplete URL used by the module on a per-search
  basis. The value should be an associative array mapping autocomplete search
  machine names to their custom URLs. The script will receive the user input as
  the "search" GET parameter and should respond with a JSON dictionary mapping
  suggestions to an HTML string that should be displayed for them.
  As the URL you can either use a relative path on the site or an absolute URL.
  Use absolute URLs to avoid problems with things like language-specific path
  prefixes. Note, though, that external URLs might not work due to security
  restrictions in browsers.
  Instead of a URL you can also set an associative array. This should have a
  valid callback in its "#callback" key, as described by
  callback_search_api_autocomplete_script_url() in
  search_api_autocomplete.api.php.
  See [2] for more information.

[2] https://www.drupal.org/node/2559699


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/SuggesterInterface.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 a autocomplete type plugin to support autocompletion for
it. See src/Type/TypeInterface.php for the plugin type documentation, or
src/Plugin/search_api_autocomplete/type/ for examples.
