Problem/Motivation
The help system needs search capability.
Proposed resolution
Probably, using the existing Drupal core Search module to build the search functionality would make the most sense. But build it in such a way that Search API contrib module, or other search modules, could easily grab the help text to index and make it searchable.
A note about caching:
- We're really only concerned here about caching for the search results page.
- The Search module already puts cache tags in based on the search index (which we have a test assert for). So that means whenever the search index changes (i.e. for whatever reason we have decided to add, delete, or update an entry for a help item), the search results page cache is invalidated. That should be sufficient to take into account the idea that if the list of (and contents of) help topics that are searchable changes for any reason, we should invalidate the search results page (because you would get different search results potentially).
- We do also want to let each item in the results, as it renders itself, to declare cache stuff (this is also in the patch/test).
- We also need a cache context for user permissions, because which items can be searched depends on user permissions.
- We should also restrict the search to only look for topics in the current page language, and add a context for the interface language.
Remaining tasks
- [Done] Implement search indexing and searching, using the core Search module. The latest patch (#54) has this working. Here is what the search results look like:
![Search results output screenshot]()
- [Done] Once it's finalized, we'll need to update its hook_help, and also add a Help Topic for it. NOTE: The help topic could use some links to help topics that don't yet exist about creating search pages and block placement. We'll have to do those later when we clean everything up in the topics on #2687107: Reorganize topics into sensible outline, and/or write more topics so I'll add a note to that issue.
- [Done] Add a search box to the main Help page. This depended on #3067943: Add capability for search blocks on non-default search and looks like this:
![Help page screenshot showing help search block]()
- [Not doing at least now] Possibly add search block to other admin pages?
- [Not doing at least now] We discussed having a keyword functionality -- a field added to the HelpTopic plugin that would define keywords that could be emphasized in the search, but decided that would not be part of this patch.
- [Done] Write a test. Things to test:
- [Done] If you enable Seven theme, you get the search block present on the help page.
- [Done] Search works for some keywords. Probably best to use the test module HelpSection plugin for that.
- [Done] Search permissions -- both the overall permission and the one that is used for a given help section. The existing help tests verify this with a section that has permissions, so we could make that HelpSection plugin searchable for further testing.
- [Done] Internationalization of search -- again with that test plugin... the HelpSection plugins have control over how to render items for indexing/results in a given language, so it would not be too hard to fake the internationalization bit in the test.
- [Done] Also add tests in the Help Topics module that verify that searching works with Help Topics in particular, and the internationalization of search works for Help Topics. But best to have the main tests independent of Help Topics I think?
- [Done] Cache tags/contexts/etc.
User interface changes
Help topics provided by the Help Topics module will be searchable. There is a new block on the main Help page that lets you search help.
API changes
No changes to existing APIs.
New API: HelpSection plugins that also implement the new interface \Drupal\help_topics\SearchableHelpInterface will make their topics searchable. So far, only the HelpTopicsSection in the help_topics module implements this interface.
Data model changes
A new database table help_search_items is added to keep track of the IDs of help topics that are searchable.
Release notes snippet
We have added a new search type (that is, a new @SearchPlugin plugin) to Core, to go along with the Node and User search types that already existed. This search type is for searching help, and its plugin is called \Drupal\help_topics\Plugin\Search\HelpSearch (it is in the experimental Help Topics module). Using this type of search, administrators can define search pages that will provide help search to site users with permission to view help.
Modules that provide @HelpSection plugins (which define sections for the admin/help page) can make their help text searchable by implementing a new interface \Drupal\help_topics\SearchableHelpInterface on their HelpSection class, which requires implementing two methods: listSearchableTopics() to list the IDs of help topics that should be searchable, and renderTopicForSearch(), which renders a single ID for either help indexing or help search results. As an example, see the \Drupal\help_topics\Plugin\HelpSection\HelpTopicsSection plugin, which is currently the only HelpSection plugin that implements this interface. (So, currently if you search help, you are only searching Help Topics managed by the Help Topics experimental module.)