The "No results" text is not correct for UserSearch -- search help needs to be per-plugin, not global

Updated: Comment #15

Problem/Motivation

Node search and user search have different syntax, neither of which is obvious to users. So, we should display searching help, as well as some generic text if there are no search results returned, and the searching help and no-results text needs to be specific to the search page/plugin.

Currently, this is a major usability bug: if you are searching using the UserSearch (or any other) plugin and get no results, the screen will display the infamous "bike shed" text. In the case of UserSearch, the text you get is a blatant lie: this text doesn't apply to UserSearch or other plugins, only to NodeSearch. Here is a screen shot from Drupal 7 (Drupal 8 looks similar):

This issue is also kind of a feature request, because currently there is no help displayed at all unless you do a search that ends up with no results. So instead of only displaying help if the user gets no results, it would be useful to have help available before you search, or if you got some results but they weren't what you expected.

The text (whether displayed for no results or as help in general) also needs to be specific to each search plugin. Some plugins might choose to make it configurable per page, but that is not needed for the Node or User search plugins.

Proposed resolution

1. Add a method to the search plugin interface that lets plugins return searching help.

The text for NodeSearch should cover:
- ability to use AND and OR
- the fact that these keywords need to be ALL UPPER CASE and in English specifically.
- the fact that only exact keywords are matched [another good argument for needing configurable text, because if someone is using a stemming module, they would not want to mention this!]
- A keyword preceded by a hyphen means "not keyword"
- You have to have at least one "positive" keyword included.
- The length words have to be to not be ignored
- Phrases can be enclosed in quotes, and must match exactly
- Punctuation is removed from the middle of numeric "words", so that e.g. 01/02/2009 will match 01-02-2009.

The text for UserSearch should cover:
- You're searching for a substring in a user name
- You can use * for a wildcard... at least the code looks like it's trying to support this?

The default text should either be empty on the base plugin, or possibly it should be the NodeSearch text (which would be appropriate for any plugin using the Core search query class).

2. Display the help below the search form (not in the block, but on the search page), in a collapsed fieldset/details element, or on a separate page (with a link), or something like that. [decided to use a link]

3. Display generic text, just saying "No results" or something like that, when there are no search results instead of the "bike shed" text that is currently displayed (which is not correct for all search plugins).

See the "UI Changes" section below for the UI that was chosen here.

Remaining tasks

Write patch with tests. [done]

Review patch.

Commit patch.

Beta phase evaluation

User interface changes

- Users will have help available for searching, even before searching or after a successful search.
- The text displayed when there are no search results will be a generic "no results" instead of the currently incorrect "bike shed" search help.

The result of this patch is that the Search page looks like this:

Clicking this link will take you to search/(your search path)/help, where you'll see the help provided by the search plugin.

The help for NodeSearch says:

Search help

• Search looks for exact, case-insensitive keywords; keywords shorter than a minimum length are ignored.
• Use upper-case OR to get more results. Example: cat OR dog (content contains either "cat" or "dog").
• You can use upper-case AND to require all words, but this is the same as the default behavior. Example: cat AND dog (same as cat dog, content must contain both "cat" and "dog").
• Use quotes to search for a phrase. Example: "the cat eats mice".
• You can precede keywords by - to exclude them; you must still have at least one "positive" keyword. Example: cat -dog (content must contain cat and cannot contain dog).

And the UserSearch help says:

Search help

• User search looks for user names and partial user names. Example: mar would match usernames mar, delmar, and maryjane.
• You can use * as a wildcard within your keyword. Example: m*r would match user names mar, delmar, and elementary.

API changes

New method on SearchInterface, with default implementation on SearchPluginBase.

Original report by douggreen

Few users know the power and flexibility of the search syntax. The search.module currently supports an implied AND between words with an optional, phrases and exclusionary terms. I propose two changes:

1. Add a help link to to the search page.
2. As an adventurous user, I tried using lower case "or" and when this didn't work, I didn't try it again. We could improve this user experience by either (a) supporting case-insensitive OR, or (b) add a warning message to the user when one of the terms is lower case 'or'. Google does the latter, using the message "Try uppercase 'OR' to search for either of two terms." However, Google also searches for or=OR=Oregon. Since we exclude terms that are 3 characters or less (this is configurable, but 3 characters is the default), I think that option (a) is better for Drupal.