Drupal Canvas

In Drupal Canvas, a search page is a search layout component with the search components in its slots. The components are in the Canvas library under Search Components. Canvas needs the Search Web Components: Canvas submodule, see Install.

The two search layout components wrap their slots in a search root, which the components search through:

• Search layout, one column has three rows at the top, a main slot, and three rows at the bottom.
• Search layout, two columns has three rows at the top, a sidebar and a main column of five slots each, and three rows at the bottom.

A component placed outside a search layout is not connected to a search and does nothing. The exception is Search box, which sends the visitor to a search page from anywhere, e.g., a header. For a page without a layout, the Search root component is the search-root element on its own, with one slot for the components.

Slots

Rows and columns	Slots
Top rows	Top 1 to Top 3 (topOne to topThree)
Sidebar	Sidebar 1 to Sidebar 5 (sidebarOne to sidebarFive)
Main column	Main 1 to Main 5 (mainOne to mainFive)
Bottom rows	Bottom 1 to Bottom 3 (bottomOne to bottomThree)

The one column layout has Top 1 to Top 3, Main (main), and Bottom 1 to Bottom 3.

An empty slot prints nothing. Column widths splits the sidebar and main columns, from 15%/85% to 85%/15% with the sidebar first. The default is 25%/75%. On screens narrower than 40em the main column shows below the sidebar.

To change the space between the columns, set the CSS variable --search-layout-column-gap. The default is 2rem:

.search-layout--two-column {
  --search-layout-column-gap: 1rem;
}

Layout settings

Set the endpoint first. Until it is set, the layout searches nothing. Both layouts have these search root settings:

• Endpoint: the endpoint this search uses, picked from the site's endpoints. For an endpoint on another site, enter its URL under Endpoint URL (manual entry).
• Additional parameters: a filter added to every search. Visitors cannot see or remove it. Write it as a query string, e.g., ?f[type]=recipe. It is not included in the page URL.
• Default results per page: set it to the endpoint's Limit. For the page sizes, see Page sizes.
• Default result display: the key of the listing layout the page starts with, e.g., list. For the listing layouts, see Listing layouts.
• Do not update the page URL: off by default. When it is on, the page URL stays the same while visitors search, and the search root ignores search parameters in the URL the page is opened with. A search cannot be bookmarked or shared, and a Search box cannot send keywords to the search page.
• A11y: Results announcement, A11y: One result announcement, A11y: No results announcement, and A11y: Search error announcement: what screen readers hear after each search. A11y: Do not announce searches turns the announcements off. Use it on a page that announces the result count itself.

The filter dialog

The two columns layout can hide the Sidebar 3 (dialog controlled) slot behind a button on narrow screens, the filter dialog. Place the facets in that slot and a Search dialog toggle component in another slot, e.g., Top 2. For what the dialog does and when to make it modal, see The filter dialog.

• Enable the dialog turns the filter dialog on.
• Dialog breakpoint: the widest screen, in pixels, on which the slot opens as a dialog. The default is 768. -1 always uses a dialog and 0 never does.
• Close text: the text of the dialog's close button.
• Close button position: top, bottom, both, or none.
• Modal: whether the open dialog blocks the page.
• A11y: Dialog name: the name screen readers announce for the dialog.

The components

Each component renders one element. For the available settings, see the component's page in Storybook:

Component	Element
Facet buttons	facet-button
Facet checkboxes	facet-checkbox
Facet dropdown	facet-dropdown
Facet dropdown (HTML)	facet-dropdown-html
Search applied facets	search-applied-facets
Search box	search-box
Search dialog pane	search-dialog-pane
Search dialog toggle	search-dialog-toggle
Search did you mean	search-did-you-mean
Search input	search-input
Search loading indicator	search-loading-indicator
Search no results message	search-no-results-message
Search result summary	search-result-summary
Search results	search-results
Search results per page	search-results-per-page
Search results switcher	search-results-switcher
Search root	search-root
Search simple pager	search-simple-pager
Search sort	search-sort

Fields whose titles start with A11y: hold text that only screen readers announce. For what to set, see Accessibility.

Facet components

Facet lists the facets on the site's endpoints that use the component's widget. Facet key (manual entry) (key) takes any facet key. The facet's settings in the endpoint's response win over the component's other settings, e.g., Show counts (showCount), unless Prefer attributes (preferAttributes) is on. For the settings a facet sends, see Where a setting comes from.

Option rows

Search sort, Search results per page, and Search results switcher can override the endpoint's options with their own. Sort options (sorts), Page size options and Display options (options) take one row per option. For the rows, see Sort options, Page sizes, and Listing layouts.

Result mappings

Search results can override the endpoint's result elements with its own. Result field (resultField) names the match field, and Result mappings (mappings) is JSON in the shape of the response's mappings, see The mappings shape.