README.txt in Search API Autocomplete 7

Search API autocomplete
-----------------------

Adds autocomplete capabilities for Search API searches.


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

- Necessary server feature

The default suggester plugin included in this module retrieves autocomplete
suggestions from the server. For this to work, the server has to support the
"search_api_autocomplete" feature. Having autocompletion on other servers is
only possible if you install a module provide another suggester plugin.
Currently, the Solr service class [1] and the Database Search [2] are known to
support this feature.

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

- 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.

NOTE: Searches using the "Multi-Index Searches" module [3] are currently not
supported by this module.

[3] https://drupal.org/project/search_api_multi

- 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" 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_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_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 [4] for more information.

[4] 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
hook_search_api_autocomplete_suggester_info() documentation in
search_api_autocomplete.api.php.

- Supporting autocompletion with a service class

To support autocompletion with a service class, the class has to support the
"search_api_autocomplete" feature. This will necessitate the service class to
have a getAutocompleteSuggestions() method as detailed in the interface in
search_api_autocomplete.interface.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 use hook_search_api_autocomplete_types() to tell this module
about it. For details, see the hook documentation in the
search_api_autocomplete.api.php file, or look at the existing implementations
in search_api_autocomplete.search_api_page.inc and
search_api_autocomplete.search_api_views.inc.