Adding Search to Your Site

1. A visitor types a query into the search box and presses Enter, or clicks the search button.
2. The box sends them to the results page, passing the query in the URL.
3. The results module on that page reads the query, searches the index for the current domain and language, and renders what it finds.

The search box is configured with the address of the results page. If you move or rename the results page, update the box to match, or searching will lead nowhere.

Note
Because the query travels in the URL, a results page can be linked to directly with a query already in it — useful for "see all results for…" links elsewhere on the site.

1. Create an ordinary page where the results should appear. The default theme expects one at /Search.
2. Place the search results module on it, as you would any other module.
3. Confirm the search box points at that page.
4. Build the index if you have not already, then search from the live site.

Note
The results module renders nothing at all when the page is opened without a query. That is expected — the page is only meaningful when arrived at from a search. Give it a heading or introduction of its own if you want it to look deliberate when reached directly.

Out of the box, without any development work:

Note
Only categories actually present in the current results appear in the filter tree, and the counts reflect that result set. A category nobody has applied to a page will never show up here — see Content, Location and Security Categories.

The module fetches the whole result set once, then filters and pages it in the visitor's browser. Switching views, ticking a category, and moving between pages are all instant, with no round trip to the server.

That is the right trade for typical sites, but it is worth knowing when tuning a large one: a query matching a very large number of pages sends all of them to the browser at once. If your site is big enough for that to matter, narrow what gets indexed rather than expecting the results page to cope — see Controlling Which Pages Are Indexed.

The module is intended to be customised. How a result looks is defined by two templates held in the module itself — one for the list view, one for the grid view — each a block of ordinary markup with placeholders substituted per result:

Restyling results, changing what each one shows, or adding a third view is a matter of editing those templates. This is theme work rather than something a content author does, but it does not require touching the search code — only the markup.

Caution
The default module does not filter results by security group. Applying security groups to results is development work that has to be added to the results module deliberately. See Content, Location and Security Categories.

The supplied module wraps its own markup in ignore markers, so the crawler does not index the results page's furniture — its filter labels, view buttons and template markup.

This matters more than it first appears. Without it, the search page itself becomes a page full of search-related words, and starts turning up in its own results. If you build a results page of your own, wrap it the same way. See Controlling Indexing from Page Markup.

The supplied search box does more than collect text. As the visitor types it offers suggestions drawn from the index and from previous popular searches, showing how many results each would return, and pressing Enter runs the search.

Its suggestions come from the index for the current domain and language, which has two consequences worth knowing:

• Suggestion quality improves as the index matures. A freshly built index suggests less than an established one.
• Terms the engine does not recognise can be suggested against unless they are listed under Custom Words. See Custom Words and Stop Lists.

Important

If the search box appears on the site reading Search is disabled and will not accept input, the index has not been built for that domain and language. The box checks for an index before enabling itself, so this is the expected appearance on a site where search is configured but never built, and on a newly restored environment whose index files did not come across. Build the index and it enables itself. See Enabling Search and Building the Index.

Both pieces are part of the site theme, unpacked when the site is created:

Because they are unpacked into the site rather than locked in the platform, they can be edited freely — and a site created some time ago has the version of them that shipped then, not the current one.

Note
Both resolve the index location through the platform rather than by a configured path, so a correctly configured domain needs no path setting here. Do not hard-code an index path into a customised results page; it will break the moment a second language or domain is added.