[en] Search in a theme

[en] The search engine is chosen in the layout's Search settings: Nexus Search, Algolia or Coveo. Your theme provides the search box, and Paligo provides everything else: the index, the scripts that run the search, and a search results page. The theme works with every search engine without changes.

[en] Add the search box

[en] Place paligo_search_box() where the search box goes:

{{ paligo_search_box() }}

[en] By default, results drop down under the box as the reader types, with a link to see all results. For the search results page, use paligo_search_box('page'), which lists the results on the page, keeps the search in the page address, and shows taxonomy filters when the layout has them turned on.

{# templates/search.html.twig #}
{% extends 'base.html.twig' %}
{% block content %}
    <main>
        <h1>{{ page.title }}</h1>
        {{ paligo_search_box('page') }}
    </main>
{% endblock %}

[en] When the layout has no search engine, paligo_search_box() produces nothing and no search page is published.

[en] Style the search box

[en] The search box and its results use these classes:

[en] Class	[en] Element
[en] `site-search`	[en] The whole search box. `data-search-mode` is `dropdown` or `page`.
[en] `site-search__form`	[en] The form.
[en] `site-search__input`	[en] The text field.
[en] `site-search__clear`	[en] The button that clears the text field.
[en] `site-search__panel`	[en] The area that holds the results.
[en] `site-search__status`	[en] The line that says how many results there are.
[en] `site-search__results`	[en] The list of results.
[en] `site-search__result`, `site-search__result-link`, `site-search__result-title`, `site-search__result-excerpt`	[en] One result, its link, title and excerpt. The search words in the excerpt are in `<mark>`.
[en] `site-search__sub`, `site-search__sub-link`	[en] Matching headings within a result.
[en] `site-search__all`	[en] The link to all results, in a dropdown.
[en] `site-search__more`	[en] The button that loads more results, on the search page.
[en] `site-search__facets`	[en] The taxonomy filters, on the search page.

[en] The highlighted result has the class is-active.

[en] Write your own search box

[en] You can write the search box's HTML yourself, for example to add your own icon or button, or to put it in a different structure. Paligo's search script finds every element with the class site-search on the page, connects it to the layout's search engine and fills in the results. Your markup only has to use the class names the script looks for.

[en] This example writes the search box once, as a macro, and uses it in two places: as a dropdown in the header of every page, and as a full search on the search results page.

[en] templates/partials/search-box.html.twig:

{% macro box(mode, id, placeholder, strings) %}
<div class="site-search" data-search-mode="{{ mode }}">
  <form class="site-search__form" role="search" method="get" action="search.html">
    <input class="site-search__input" type="search" name="q" autocomplete="off"
        placeholder="{{ placeholder }}" aria-label="{{ placeholder }}"
        {%- if mode == 'dropdown' %} role="combobox" aria-expanded="false" aria-controls="{{ id }}-panel" aria-autocomplete="list"{% endif %}>
    <button type="button" class="site-search__clear" hidden aria-label="{{ strings.clearSearch|default('Clear search') }}">&times;</button>
  </form>
  <div class="site-search__panel" id="{{ id }}-panel"{% if mode == 'dropdown' %} hidden{% endif %}>
    <p class="site-search__status" role="status" aria-live="polite"></p>
    <ul class="site-search__results"></ul>
    {% if mode == 'dropdown' %}
      <a class="site-search__all" hidden></a>
    {% else %}
      <button type="button" class="site-search__more" hidden>{{ strings.searchMore|default('Load more results') }}</button>
    {% endif %}
  </div>
  {% if mode == 'page' %}
    <div class="site-search__facets" hidden></div>
  {% endif %}
</div>
{% endmacro %}

[en] The macro takes the mode (dropdown or page), an ID that is unique on the page, the placeholder text and the theme's texts. The ID connects the text field to its results, so that screen readers can announce them.

[en] templates/base.html.twig, with the header search in a block of its own:

{% import 'partials/search-box.html.twig' as search %}
<!doctype html>
<html lang="{{ site.lang }}"{% if site.dir %} dir="{{ site.dir }}"{% endif %}>
<head>
    <meta charset="utf-8">
    <title>{% block title %}{{ page.title }} | {{ site.title }}{% endblock %}</title>
    {{ paligo.head }}
</head>
<body>
    <header>
        {% block header_search %}
            {% if site.search.backend|default('none') != 'none' %}
                {{ search.box('dropdown', 'header-search', site.strings.searchPlaceholder|default('Search'), theme.strings) }}
            {% endif %}
        {% endblock %}
        {% include 'partials/language-menu.html.twig' %}
    </header>
    {% block content %}{% endblock %}
    {{ paligo.foot }}
</body>
</html>

[en] templates/search.html.twig, which empties the header search, because the page has its own:

{% extends 'base.html.twig' %}
{% import 'partials/search-box.html.twig' as search %}
{% block header_search %}{% endblock %}

{% block content %}
    <main>
        <h1>{{ page.title }}</h1>
        {{ search.box('page', 'search-page', site.strings.searchPlaceholder|default('Search'), theme.strings) }}
    </main>
{% endblock %}

[en] The search results page uses the address search.html, which is the action of the form. If the reader can't run scripts, the form still opens the search results page.

[en] Paligo checks a theme's search box when the theme is uploaded:

[en] These parts are required, and a missing one is an error: a <form class="site-search__form"> with an action, a site-search__input field named q, a site-search__panel and a site-search__results.
[en] These parts are recommended, and a missing one is a warning: data-search-mode set to dropdown or page, a site-search__status and a site-search__clear, a site-search__all in a dropdown, and a site-search__more and site-search__facets on the search page.

[en] Translate the search texts

[en] The search texts are in English unless your theme's translation files provide these keys. See [en] Translate a theme.

[en] Key	[en] Text
[en] `clearSearch`	[en] The name of the clear button.
[en] `searchMore`	[en] The button that loads more results.
[en] `searchAll`	[en] The link to all results. `[COUNT]` is replaced by the number of results.
[en] `searchPage`	[en] The name of the search results page.
[en] `searchNone`, `searchOne`, `searchMany`	[en] The result count. `[COUNT]` is the number and `[SEARCH_TERM]` the search.
[en] `searchFilters`	[en] The heading of the filters.
[en] `searchUnavailable`	[en] Shown when search can't be loaded.
[en] `searchError`	[en] Shown when a search fails.

[en] Keep page furniture out of the index

[en] Nexus Search indexes the whole page. To leave a part of the page out of the index, such as a navigation menu or a footer, add data-pagefind-ignore to it:

<nav class="sidebar" data-pagefind-ignore>…</nav>