You are here

README.txt in Fast Autocomplete 8

Same filename and directory in other branches
  1. 7 README.txt
CONTENTS OF THIS FILE
---------------------

 * Introduction
 * Requirements
 * Installation
 * Configuration
 * Maintainers


INTRODUCTION
------------

The Fast Autocomplete module provides fast IMDB-like suggestions below a text
input field. Suggestions are stored as JSON files in the public files folder so
that they can be provided to the browser relatively fast without the need for
Drupal to be bootstrapped.

When the JSON file with the suggestions for the entered combination of
characters does not exist, Drupal kicks in and returns suggestions (and stores
in a JSON file in the public files folder for future use). The JSON files are
periodically deleted after a configurable expiration period.

The suggestions are retrieved using a search service/plugin. The search
services/plugin provided by the module can be altered through hooks or extended
in custom implementations of the service class (Drupal 7) or added by
implementing a custom plugin (Drupal 8).

Basic search services/plugins provided by the module are:
 * Basic title search: performs a LIKE query on node titles
 * Search API: can query Search API indexes

The output of the suggestions (when they are nodes) can be configured using view
modes. Combined with for instance the Display Suite module you can create really
nice formatted suggestions.

 * For a full description of the module visit:
   https://www.drupal.org/project/fac

 * To submit bug reports and feature suggestions, or to track changes visit:
   https://www.drupal.org/project/issues/fac


REQUIREMENTS
------------

This module requires no modules outside of Drupal core.


INSTALLATION
------------

 * Install the Fast Autocomplete module as you would normally install a
   contributed Drupal module. Visit https://www.drupal.org/node/1897420 for
   further information.
 * If you want to use highlighting of the search keys in the suggestions and you
   do not want to use the script from a CDN (by default the script is included
   from a CDN) then you need to download the mark.js script from
   https://cdnjs.cloudflare.com/ajax/libs/mark.js/8.11.1/jquery.mark.min.js
   and save it in the /libraries/mark.js/ folder in your codebase. You can
   disable the "use CDN" option in the general settings form of the module.


CONFIGURATION
-------------

Navigate to Administration > Configuration > Search > fac to create one or more
Fast Autocomplete configurations. For each configuration you can select which
search plugin is used to create the search suggestions. You are able to
configure the behavior of the Fast Autocomplete plugin like what input to enable
the plugin on, how many suggestions to show, what view mode per entity type to
use for the suggestions, etc.

Deleting Suggestion Files:

Besides the periodical cleanup of the JSON files that contain the suggestions
that you can configure you can also manually delete all generated JSON files per
configuration. There is an option "Delete json files" in the operations
dropdown of each configuration at /admin/config/search/fac.

Alter Hooks:

There is hook_fac_empty_result_alter(&$empty_result, $context) that you can use
to alter the empty result content. For example, you can create an "Empty results
suggestions menu" that an editor can maintain, load that menu and output that as
the empty result content using this hook.

Custom Search Plugins:

The Fast Autocomplete module uses the Drupal 8 plugin system to provide the
Search Plugins that can be used to create the suggestions list based on the user
input. You can add your own search plugin by creating a new plugin that extends
\Drupal\fac\SearchBase and implements \Drupal\fac\SearchInterface. Visit
\Drupal\fac\Plugin\Search\BasicTitleSearch and
\Drupal\fac\Plugin\Search\SearchApiSearch for reference.

How the Module Works:

Basically the module is a jQuery plugin that adds a behavior on inputs that uses
the input to retrieve a JSON file with suggestions for the term that is in the
input through AJAX and show them in a suggestion box. The JSON files are
requested from the public files directory. Only when a suggestion file doest not
exist, Drupal is bootstrapped and a controller will create the suggestions,
store the JSON file and return them in the AJAX response.

The suggestions are created using a configurable backend service. The backend
service can be basically anything that returns an array of suggestions with a
suggestion being an array of entity_type and entity_id. The configured view mode
is used to render the suggestion in the result list, so the presentation of
suggestions is configurable.

JavaScript Events:

The jQuery plugin triggers two custom events "fac:requestStart" and
"fac:requestEnd" that you can use to do something when the plugin starts a
request for suggestions. For instance you might want to show a throbber while
the plugin is retrieving suggestion by adding a class "throbbing" to the input
element. You can achieve this by adding the following example behavior in your
JavaScript:

```
  Drupal.behaviors.facExample = {
    attach: function(context, settings) {
      $(Drupal.settings.fac.inputSelectors).bind('fac:requestStart', function(e) {
        $(this).addClass('throbbing');
      });
      $(Drupal.settings.fac.inputSelectors).bind('fac:requestEnd', function(e) {
        $(this).removeClass('throbbing');
      });
    }
  };
```

Limitations:

Because of the architecture of the module to use public JSON files to provide
suggestions as fast as possible there is a security-based limitation that the
search query for suggestions is performed as an anonymous user by default.
Otherwise there could potentially be an information leakage issue because one
would be able to retrieve restricted information by requesting the public JSON
files.

If you deem the risk of information leakage to be mitigated or the effect of
leakage low or non-existent you are able to configure this behavior by
unchecking the configuration option "Perform search as anonymous user only". The
search will be performed with the permissions of the logged in user and the risk
of information leakage will be reduced by the role-based hash in the JSON files
URL that is periodically updated. The default interval is once a week.


MAINTAINERS
-----------

 * Heine Deelstra (Heine) - https://www.drupal.org/u/heine
 * Martijn Vermeulen (Marty2081) - https://www.drupal.org/u/marty2081
 * Baris Wanschers (BarisW) - https://www.drupal.org/u/barisw

Supporting organizations:

 * LimoenGroen - https://www.drupal.org/limoengroen

File

README.txt
View source
  1. CONTENTS OF THIS FILE
  2. ---------------------
  3. * Introduction
  4. * Requirements
  5. * Installation
  6. * Configuration
  7. * Maintainers
  8. INTRODUCTION
  9. ------------
  10. The Fast Autocomplete module provides fast IMDB-like suggestions below a text
  11. input field. Suggestions are stored as JSON files in the public files folder so
  12. that they can be provided to the browser relatively fast without the need for
  13. Drupal to be bootstrapped.
  14. When the JSON file with the suggestions for the entered combination of
  15. characters does not exist, Drupal kicks in and returns suggestions (and stores
  16. in a JSON file in the public files folder for future use). The JSON files are
  17. periodically deleted after a configurable expiration period.
  18. The suggestions are retrieved using a search service/plugin. The search
  19. services/plugin provided by the module can be altered through hooks or extended
  20. in custom implementations of the service class (Drupal 7) or added by
  21. implementing a custom plugin (Drupal 8).
  22. Basic search services/plugins provided by the module are:
  23. * Basic title search: performs a LIKE query on node titles
  24. * Search API: can query Search API indexes
  25. The output of the suggestions (when they are nodes) can be configured using view
  26. modes. Combined with for instance the Display Suite module you can create really
  27. nice formatted suggestions.
  28. * For a full description of the module visit:
  29. https://www.drupal.org/project/fac
  30. * To submit bug reports and feature suggestions, or to track changes visit:
  31. https://www.drupal.org/project/issues/fac
  32. REQUIREMENTS
  33. ------------
  34. This module requires no modules outside of Drupal core.
  35. INSTALLATION
  36. ------------
  37. * Install the Fast Autocomplete module as you would normally install a
  38. contributed Drupal module. Visit https://www.drupal.org/node/1897420 for
  39. further information.
  40. * If you want to use highlighting of the search keys in the suggestions and you
  41. do not want to use the script from a CDN (by default the script is included
  42. from a CDN) then you need to download the mark.js script from
  43. https://cdnjs.cloudflare.com/ajax/libs/mark.js/8.11.1/jquery.mark.min.js
  44. and save it in the /libraries/mark.js/ folder in your codebase. You can
  45. disable the "use CDN" option in the general settings form of the module.
  46. CONFIGURATION
  47. -------------
  48. Navigate to Administration > Configuration > Search > fac to create one or more
  49. Fast Autocomplete configurations. For each configuration you can select which
  50. search plugin is used to create the search suggestions. You are able to
  51. configure the behavior of the Fast Autocomplete plugin like what input to enable
  52. the plugin on, how many suggestions to show, what view mode per entity type to
  53. use for the suggestions, etc.
  54. Deleting Suggestion Files:
  55. Besides the periodical cleanup of the JSON files that contain the suggestions
  56. that you can configure you can also manually delete all generated JSON files per
  57. configuration. There is an option "Delete json files" in the operations
  58. dropdown of each configuration at /admin/config/search/fac.
  59. Alter Hooks:
  60. There is hook_fac_empty_result_alter(&$empty_result, $context) that you can use
  61. to alter the empty result content. For example, you can create an "Empty results
  62. suggestions menu" that an editor can maintain, load that menu and output that as
  63. the empty result content using this hook.
  64. Custom Search Plugins:
  65. The Fast Autocomplete module uses the Drupal 8 plugin system to provide the
  66. Search Plugins that can be used to create the suggestions list based on the user
  67. input. You can add your own search plugin by creating a new plugin that extends
  68. \Drupal\fac\SearchBase and implements \Drupal\fac\SearchInterface. Visit
  69. \Drupal\fac\Plugin\Search\BasicTitleSearch and
  70. \Drupal\fac\Plugin\Search\SearchApiSearch for reference.
  71. How the Module Works:
  72. Basically the module is a jQuery plugin that adds a behavior on inputs that uses
  73. the input to retrieve a JSON file with suggestions for the term that is in the
  74. input through AJAX and show them in a suggestion box. The JSON files are
  75. requested from the public files directory. Only when a suggestion file doest not
  76. exist, Drupal is bootstrapped and a controller will create the suggestions,
  77. store the JSON file and return them in the AJAX response.
  78. The suggestions are created using a configurable backend service. The backend
  79. service can be basically anything that returns an array of suggestions with a
  80. suggestion being an array of entity_type and entity_id. The configured view mode
  81. is used to render the suggestion in the result list, so the presentation of
  82. suggestions is configurable.
  83. JavaScript Events:
  84. The jQuery plugin triggers two custom events "fac:requestStart" and
  85. "fac:requestEnd" that you can use to do something when the plugin starts a
  86. request for suggestions. For instance you might want to show a throbber while
  87. the plugin is retrieving suggestion by adding a class "throbbing" to the input
  88. element. You can achieve this by adding the following example behavior in your
  89. JavaScript:
  90. ```
  91. Drupal.behaviors.facExample = {
  92. attach: function(context, settings) {
  93. $(Drupal.settings.fac.inputSelectors).bind('fac:requestStart', function(e) {
  94. $(this).addClass('throbbing');
  95. });
  96. $(Drupal.settings.fac.inputSelectors).bind('fac:requestEnd', function(e) {
  97. $(this).removeClass('throbbing');
  98. });
  99. }
  100. };
  101. ```
  102. Limitations:
  103. Because of the architecture of the module to use public JSON files to provide
  104. suggestions as fast as possible there is a security-based limitation that the
  105. search query for suggestions is performed as an anonymous user by default.
  106. Otherwise there could potentially be an information leakage issue because one
  107. would be able to retrieve restricted information by requesting the public JSON
  108. files.
  109. If you deem the risk of information leakage to be mitigated or the effect of
  110. leakage low or non-existent you are able to configure this behavior by
  111. unchecking the configuration option "Perform search as anonymous user only". The
  112. search will be performed with the permissions of the logged in user and the risk
  113. of information leakage will be reduced by the role-based hash in the JSON files
  114. URL that is periodically updated. The default interval is once a week.
  115. MAINTAINERS
  116. -----------
  117. * Heine Deelstra (Heine) - https://www.drupal.org/u/heine
  118. * Martijn Vermeulen (Marty2081) - https://www.drupal.org/u/marty2081
  119. * Baris Wanschers (BarisW) - https://www.drupal.org/u/barisw
  120. Supporting organizations:
  121. * LimoenGroen - https://www.drupal.org/limoengroen