Build search experiences in Canvas

This guide is for marketers, content authors, and merchandisers. It tells you how to build and change search experiences in Uniform Canvas with the search components.

After a developer adds the search components to your project, you do not need a developer for daily work. You can build a search page, add filters and sort options, limit the results, show recommendations, and show search results on any page. For the developer setup, see Search SDK and API.

Prerequisites

  • Uniform Search is on for your project, and your content is in the search index. If Uniform Search is not on, request activation.
  • A developer added the search components to your project and to your site.
  • A composition type in your project lets you put the Search Engine component in one of its slots.
  • You have permission to edit and publish compositions. See Roles and permissions.

The search components are Canvas components in the Uniform Search category. Each component shows one part of the search experience to the visitor.

The Search Engine component is the container of a search experience. It does not show content of its own. It holds the other search components and sends the search to Uniform Search.

The Search Engine component has 3 slots:

SlotComponents that you can put in the slot
Search TopSearch Box, Search Sort, Search Pagination
Search MainSearch Results, Facet Container
Search BottomSearch Pagination

Put these components in the slots of a Search Engine component. They do not work outside of it.

ComponentWhat the visitor sees
Search BoxA text box for the search words.
Search ResultsThe list of results as cards, with the number of results.
Facet ContainerA panel that holds the facets. It shows nothing of its own.
Search Facet1 filter, for example "Brand" or "Price", with the values and the number of results for each value. Put it in a Facet Container.
Search SortA list of sort options, for example "Newest Arrivals" or "Price: Lowest first".
Search PaginationPage numbers, Prev and Next buttons, and a list to select the number of results on each page.

The developer decides how each result card looks. Each content type can have its own card design.

You can put these components on any page. They do not need a Search Engine component.

ComponentWhat the visitor sees
Search AutocompleteA search box that shows suggestions while the visitor types. Use it in a site header. When the visitor pushes Enter, the site opens your search page.
RecommendationsA list of content that matches the interests of the visitor. See Show recommendations.

Your project has 2 component patterns that you can use as a start:

PatternWhat it contains
Search EngineA full search page. It has a Search Engine with these child components: Search Box, Search Sort with 7 sort options, Facet Container, Search Results, and Search Pagination with the page sizes 8, 16, and 32.
Search AutocompleteA Search Autocomplete component that sends the visitor to /search.

The Search Engine pattern has these sort options:

  • "Relevance"
  • "Behavior relevancy"
  • "Newest Arrivals"
  • "Alphabetically: A-Z" and "Alphabetically: Z-A"
  • "Rating: Highest first" and "Rating: Lowest first"

Some of these options need fields that your content possibly does not have. Edit the pattern to remove the options that you do not need.

All the components inside one Search Engine use the same search. When the visitor types a word, selects a facet value, or selects a sort option, all the components update together. For example, the facets show the number of results for the current search words.

The page URL keeps the search words, the facet values, the sort option, and the page number. A visitor can copy the URL and send it to a friend. The friend sees the same results.

The Search Engine component controls which results can show. The child components control what the visitor sees and does. For example, you set the sort options on the Search Sort component, and you set the page sizes on the Search Pagination component.

Build a search page#

You can build a search page in 2 ways:

  • Add the Search Engine pattern. This is the fastest way.
  • Add each component yourself. Use this way when you want a different layout or fewer components.
  1. In Canvas, open the composition for your search page. If you do not have one, create a composition.
  2. In the slot for the page content, click the plus icon .
  3. Select the Search Engine pattern.
  4. Select the Search Engine component in the component tree.
  5. Set the parameters of the Search Engine component. See Search Engine parameters.
  6. Add facets to the Facet Container. See Add a facet.
  7. Click Save.

On a page that uses the pattern, you can change these Search Engine parameters: Query By, Base Filters, Typo-Tolerance Level, and Entry Url Mapping. You can also add facets to the Facet Container.

To change other parameters, such as the sort options or the page sizes, edit the pattern. A change to the pattern changes all the pages that use the pattern.

  1. In Canvas, open the composition for your search page.
  2. In the slot for the page content, click the plus icon .
  3. Select the Search Engine component.
  4. Set the parameters of the Search Engine component. See Search Engine parameters.
  5. In the Search Top slot, add a Search Box component.
  6. In the Search Main slot, add a Facet Container component.
  7. In the Search Main slot, add a Search Results component.
  8. In the Search Bottom slot, add a Search Pagination component.
  9. Add at least 1 Page Size item to the Page Sizes parameter. See Search Pagination parameters.
  10. Optional: in the Search Top slot, add a Search Sort component. See Add sort options.
  11. Click Save.

A facet lets the visitor filter the results by the values of 1 field, for example by brand. Before you add a facet, make sure that the field has Facet on in the schema. A team admin sets this in the Uniform Search tool.

  1. In the Facet Container, click the plus icon .
  2. Select the Search Facet component.
  3. In Facet by field, select the field. See Facet By Field.
  4. In Type, select how the visitor selects values:
    • Select: the visitor can select 1 value.
    • Multi Select: the visitor can select more than 1 value.
    • Range: the visitor moves a slider to set a minimum and a maximum. Use this type only for number fields, such as a price.
  5. In Title, enter the heading of the facet, for example "Brand".
  6. Do steps 1 to 5 again for each facet that you want.
  1. Open the composition or the component pattern for your site header.
  2. In the slot for the search box, click the plus icon .
  3. Select the Search Autocomplete pattern or the Search Autocomplete component.
  4. In Results Page Path, enter the path of your search page, for example /search.
  5. Set the other parameters. See Search Autocomplete parameters.
  6. Click Save.

When the visitor pushes Enter, the site opens the search page with the search words. The search page shows the results for these words.

Some parameters of the search components have a special editor. The editor reads the schema of your search index and shows only the fields that you can use for that task.

Sometimes an editor shows "No indexed collection found" or a message such as "No sortable fields found". This occurs if the search index has no content yet, or if no field has the necessary option. Speak to your team admin.

The Query By parameter uses the Query By Fields editor. It sets which fields Uniform Search compares with the search words of the visitor.

The order of the fields is important. A result that matches a field at the top of the list ranks higher than a result that matches a field lower in the list.

  1. Click Add field….
  2. Select a field, for example title.
  3. Do steps 1 and 2 again for each field that you want.
  4. Put the most important field first, for example the title before the description.

Only text fields show in the list.

The Query By Fields editor with 4 fields in this order: title, name, shortDescription and accumulatedContent.
The Query By Fields editor with 4 fields in order of importance.

The Base Filters parameter of the Search Engine uses the Filter By Builder editor. A base filter limits the results that the visitor can see. The visitor cannot remove a base filter.

For example, use a base filter to make a search page that shows only the products in the category "Shoes".

  1. Click + Add filter.
  2. In Field, select a field, for example category.
  3. In Operator, select how to compare the value, for example exact match.
  4. In Value, enter or select the value, for example "Shoes". The editor suggests values from your content.
  5. To add more conditions, do steps 1 to 4 again.
  6. To change how 2 conditions connect, click the Connector between them. && shows only the results that match both conditions. || shows the results that match 1 of the conditions.

The filter_by preview: line shows the full filter. To remove a condition, click Remove condition.

The operators that you can select change with the type of the field:

Field typeOperators
Textcontains, exact match, not equals, not contains
Numberequals, not equals, less than, greater than, less than or equal, greater than or equal
List of valuescontains, not contains, word match
Yes or nois

Only fields that have Facet on in the schema show in the Field list.

To use a value from the page URL, click Insert dynamic token in Value. For example, on a dynamic category page, the filter can use the category of the current page. For more about dynamic pages, see Project maps.

The Filter By Builder with 2 conditions joined by AND: category exact match Shoes, and inStock is true. The filter_by preview shows category:= Shoes && inStock:= true.
A base filter that shows only the shoes that are in stock.

The Facet by field parameter of the Search Facet uses the Facet By Field editor. It sets the field that gives the values of the facet.

  1. Click — select field —.
  2. Select the field. Each option shows the field name and the field type.

Only fields that have Facet on in the schema show in the list.

The Field of each Order By item in the Search Sort uses the Sort By Field editor. It sets how 1 sort option orders the results.

  1. In Field, select 1 of these options:
    • Relevance (default): the best match for the search words comes first.
    • Behavior relevancy (Uniform Context): the results that match the interests of the visitor come first. See Behavior relevancy.
    • A field from the list, for example price.
  2. If you selected a field, select a Direction: Ascending or Descending.

Ascending puts the lowest value or the start of the alphabet first. Descending puts the highest value or the most recent date first. The Preview: line shows the result of your selection.

Only fields that have Sort on in the schema show in the list.

The Sort By Field editor with the Field list open. Relevance (default) and Behavior relevancy (Uniform Context) are at the top, followed by the sortable fields such as name, price, rating and publishDate.
The Sort By Field editor with the behavior relevancy option.

The Predefined Sort parameter of the Search Sort uses the Predefined Sort editor. A predefined sort puts some results first while the visitor uses the default sort option. For more, see Use a predefined sort.

Entry Url Mapping#

The Entry Url Mapping parameter uses the Entry Url Mapping editor. It tells the search components which page to open when a visitor clicks an entry in the results.

Results for compositions do not need a mapping. They use the URL of the page from your project map. Results for entries need a mapping, because an entry does not have a URL of its own.

For example, your product entries show on the dynamic page /products/:slug. The mapping tells Uniform Search to put the slug field of each product into :slug.

  1. Click + Add new mapping.
  2. In Type, select the content type of the entries, for example product.
  3. In URL path template, select the dynamic page that shows these entries.
  4. Under Map path tokens to document fields, select a field for each token, for example slug for :slug.
  5. Look at the URL preview: line. Make sure that the URL is correct.
  6. Click Add.
  7. Do steps 1 to 6 again for each content type that shows in the results.
  8. Click Close.

To change a mapping, click it. To remove a mapping, click Delete mapping.

The new mapping form of the Entry Url Mapping editor with Type product, URL path template /products/:slug (Product detail), the :slug token mapped to the slug field, and the URL preview /products/{slug}.
Map the product entries to the dynamic product page.

The Search Sort component shows a list of sort options to the visitor. You make the list with Order By items.

  1. Select the Search Sort component.
  2. In Order By, add an Order By item.
  3. In Title, enter the name that the visitor sees, for example "Price: Lowest first".
  4. In Field, select the sort. See Sort By Field.
  5. Do steps 2 to 4 again for each sort option.
  6. Move the default sort option to the top of the list.

The first item in the list is the default. The results use this order when the page opens.

Sort by a field when semantic search is on

Semantic search can be on for your project. Then a search by wording and meaning ignores a sort by a field, such as price. To make field sort options work, set Matching on the Search Engine to Exact wording only. Sort options with Behavior relevancy (Uniform Context) work in both modes.

Behavior relevancy uses Uniform Context. Uniform Context learns the interests of each visitor from the content that they look at. When the visitor selects a sort option with Behavior relevancy (Uniform Context), the results that match their interests come first. Each visitor can see a different order.

Behavior relevancy changes only the order of the results. The number of results and the facet values stay the same. If a visitor has no interests yet, the results use the relevance order.

Behavior relevancy needs no field in the schema. It uses the enrichments on your content. For more about enrichments and interests, see Personalization.

To add behavior relevancy as a sort option, add an Order By item. Then select Behavior relevancy (Uniform Context) in Field. To make it the default, move the item to the top of the list.

A predefined sort changes the default order of the results. The visitor does not see it as a sort option. Use it to put some results first, for example products that are in stock.

The predefined sort applies only while the visitor uses the default sort option. The default sort option then orders the results that are equal. When the visitor selects a different sort option, only that option applies.

  1. Select the Search Sort component.
  2. Open the Predefined Sort parameter.
  3. In Sort type, select Sort by field or Conditional rules.
  4. Do the steps for the sort type that you selected.

To sort by a field:

  1. In Field, select a field or Behavior relevancy (Uniform Context).
  2. If you selected a field, select a Direction.

To sort by conditional rules:

  1. In Direction, select Descending (matches first) or Ascending (matches last).
  2. In Rule 1, make a condition with the filter builder, for example inStock is true.
  3. To add a rule, click + Add rule.
  4. To change the priority of a rule, click Move up (higher priority) or Move down (lower priority).

The first rule has the highest priority. The results that match it come before the results that match the rules below it. The sort_by preview: line shows the result of your rules.

The Predefined Sort editor with Sort type Conditional rules and Direction Descending (matches first). Rule 1, the highest priority, is inStock is true. Rule 2, the lowest priority, is brand exact match Acme.
Conditional rules put the products in stock first, then the products of 1 brand.

The Recommendations component shows content that matches the interests of the visitor. It uses the same Uniform Context data as behavior relevancy. The visitor does not type a search. Use it, for example, on a home page or below a product.

  1. Open the composition.
  2. In a slot, click the plus icon .
  3. Select the Recommendations component.
  4. In Title, enter the heading, for example "Recommended for you".
  5. Optional: in Content Type, enter the public ID of 1 content type, for example product.
  6. Optional: in Max Recommendations, enter the number of items to show.
  7. Set Entry Url Mapping. See Entry Url Mapping.
  8. Click Save.

If the visitor has no interests yet, the component shows items in the default order. If no content matches, the component shows nothing.

Show search results on any page#

The Uniform Search data connector gets documents from the search index into any composition or entry. You connect the documents to the parameters of your own components. For example, show the 3 newest articles on a home page, or show a list of products that you select.

This is different from the Search Engine component:

  • The page does not have a search box, facets, or sort options.
  • The list is the same for all visitors. For a list for each visitor, use the Recommendations component.

The data connector gives 2 data types:

Data typeWhat it gives
Search QueryThe results of a search that you set: search words, filters, sort, and the number of results. The list updates when the content in the search index changes.
Curated ListThe documents that you select one by one, in the order that you set.

Before you create a data type, your project must have a Uniform Search data source. The data source configures itself. Its Base filter applies to all the data types that use it.

  1. Create a data type from the Uniform Search data source. For the general steps, see Composition.
  2. Select the type of data: Search Query or Curated List.
  3. For a Search Query data type, set the fields in the table below.
  4. Click Save.
FieldWhat it does
FiltersA filter for all the data resources of this data type. It uses the filter builder.
Search fieldsThe fields that Uniform Search compares with the search words.
FacetsThe fields that give facet values in the result.
Default sortThe default order of the results.
Result countThe number of results. The default is 10.
Thumbnail fieldThe field with the image that shows next to each document in the editor.

For a Curated List data type, you can set a Filter and a Thumbnail field. The Filter only limits the documents that you can select in the editor.

  1. Open the composition.
  2. Open the data resources of the composition .
  3. Add a data resource.
  4. Select your Uniform Search data type.
  5. Configure the data resource. See the procedures below.
  6. Click Save.

To configure a Search Query data resource:

  1. Under Configure your query, enter the search words in Search…. To show all documents, leave it empty.
  2. To add a filter, open Show results and add a condition. The filters from the data source and the data type show as Predefined filters. You cannot change them here.
  3. In Sort by, select the order.
  4. Optional: in Show locale, select the locale.
  5. Optional: open Advanced. In Records to fetch, enter the number of documents.
  6. Look at Preview the results. Make sure that the documents are correct.
A Search Query data resource with the search word tent and the Filter/Sort panel open. The predefined filters include type exact match product, Sort by is rating descending, and Preview the results shows 7 matching documents.
A Search Query data resource with a filter and a preview of the results.

To configure a Curated List data resource:

  1. Under Configure your list, enter words in Search… to find documents.
  2. In Search results, click + Add next to each document that you want.
  3. In Selected, click Move up or Move down to change the order.
  4. To remove a document from the list, click Remove.
A Curated List data resource with the search word 4-season. The Search results list has + Add buttons next to each document and Added next to one that is already selected. The Selected (3) list below has move up, move down and remove buttons for each document.
Select documents and set their order in a Curated List data resource.
  1. Select the component that shows the data.
  2. Connect a parameter of the component to the data resource.
  3. Select a field from the data resource, for example the title of the first result.
  4. To show each result in a list, use a Loop component. Put a card component inside the Loop, and connect the card parameters to the fields of the loop item.

For more about data resources, connections to data, and loops, see Composition.

  1. In Canvas, look at the preview of your composition. The search components show real results from your search index.
  2. Type a search word in the preview. Make sure that the results are correct.
  3. Select facet values and sort options. Make sure that the results change as you expect.
  4. Click Publish.
  5. Open the live page on your site.
  6. Do a search on the live page. Make sure that the results, the facets, and the links in the result cards are correct.

To test behavior relevancy, look at some content on the live site first. Uniform Context then knows your interests. Do a search again, and select the behavior relevancy sort option. Your team admin can also test a visitor profile in the Uniform Search tool.

This section gives the parameters of each search component. Parameters that are not in these tables do not change the component.

ParameterWhat it does
Base FiltersLimits the results that the visitor can see. The visitor cannot remove this filter. See Filter By Builder.
Entry Url MappingSets the page that opens when the visitor clicks an entry in the results. See Entry Url Mapping.
Query BySets the fields that Uniform Search compares with the search words, in order of importance. See Query By Fields.
Typo-Tolerance LevelSets how many spelling errors a search word can have and still find results. Off: no errors. Basic: 1 error in longer words. Aggressive: up to 2 errors, also in shorter words.
MatchingSets how Uniform Search finds results. Default (wording + meaning) finds results by the words and by their meaning. Exact wording only finds only results with the same words. Use Exact wording only for searches for product codes or part numbers. If you do not set a value, Uniform Search selects the best method for your project.
ParameterWhat it does
LabelThe name of the search box. The visitor does not see it, but screen readers read it.
PlaceholderThe text in the empty search box, for example "Search products…".
ParameterWhat it does
No Results Found TextThe message when there are no results. The default is "No results found".
Try Different Filters TextThe text before the link that clears the filters. The default is "Try different filters or".
Clear All Filter TextThe text of the link that clears all the facet values. The default is "clear all filters".
ParameterWhat it does
Facet by fieldThe field that gives the facet values. See Facet By Field.
TypeHow the visitor selects values: Select, Multi Select, or Range. See Add a facet.
TitleThe heading above the facet.

The Facet Container component has no parameters.

ParameterWhat it does
Order ByThe list of sort options. Each Order By item has a Title and a Field. The first item is the default. See Add sort options.
Predefined SortA default order that the visitor does not see. See Use a predefined sort.
ParameterWhat it does
Sibling CountThe number of page numbers to show on each side of the current page. The default is 1.
Page SizesThe list of page sizes that the visitor can select. Each Page Size item has a Size, which is the number of results on 1 page. Select Default on 1 item to make it the default. You must add at least 1 item.

attention

Leave Sibling Count empty to use the default of 1. If you set a value, enter a whole number, for example 2. Do not enter text or a decimal number.

ParameterWhat it does
LabelThe name of the search box for screen readers.
PlaceholderThe text in the empty search box.
DelayThe time in milliseconds between the last key and the suggestions. The default is 150.
Minimum CharactersThe number of characters that the visitor must type before suggestions show. The default is 2.
Max ResultsThe number of suggestions. The default is 6.
Results Page PathThe path of the search page, for example /search. The site opens this page when the visitor pushes Enter.
Query ByThe fields that Uniform Search compares with the search words. See Query By Fields.
Entry Url MappingThe page that opens when the visitor clicks an entry in the suggestions. See Entry Url Mapping.
View All TextThe text of the link that opens the search page with all the results.
No Results TextThe message when there are no suggestions.
ParameterWhat it does
TitleThe heading above the recommendations.
Content TypeThe public ID of the content type to recommend, for example product. If you leave it empty, the component recommends all types of content.
Boost CategoriesThe public IDs of the enrichment categories to use, with a comma between them, for example int,brand. If you leave it empty, the component uses all categories.
Max RecommendationsThe number of items to show. The default is 4.
Entry Url MappingThe page that opens when the visitor clicks an entry. See Entry Url Mapping.
  • Put the most important fields first in Query By. The title is usually the best first field.
  • Use 3 to 6 facets. Too many facets make the page difficult to use.
  • Give each facet and each sort option a clear title that your visitors understand.
  • Use a Range facet for prices and other numbers. Use Multi Select for brands and categories.
  • Use a base filter to make a search page for 1 part of your site, for example a help center.
  • On a product list, use Behavior relevancy (Uniform Context) as the default sort.
  • Keep Typo-Tolerance Level at Basic. Use Off for pages where visitors search for codes.
  • After a change, look at the preview before you publish.

Some changes to relevance apply to all search pages. These are synonyms, curations, and stopwords. Team admins set them in the Uniform Search tool. For example, a curation can put a product at the top of the results for 1 search word. See Configure search.

ProblemCauseWhat to do
The preview shows no results.The content is not in the search index, or a base filter is too narrow.Make sure that the content is published. Remove the Base Filters conditions one at a time and look at the preview again. If the problem continues, speak to your team admin.
The preview shows no results for a locale.The search index has no content for that locale.Speak to your team admin. The locale must be in the indexing scope.
A facet shows no values.The field does not have Facet on in the schema.Ask your team admin to turn on Facet for the field. The admin possibly must do a re-index.
A field is not in the Facet by field list or the Field list of the filter builder.The field does not have Facet on in the schema.Ask your team admin to turn on Facet for the field.
A field is not in the Sort By Field list.The field does not have Sort on in the schema.Ask your team admin to turn on Sort for the field.
A sort option shows no change.The field has the same value in many documents, or the visitor has no interests for behavior relevancy.Select a field with different values. For behavior relevancy, look at some content first, then search again.
A click on a result opens the wrong page or no page.The content type has no Entry Url Mapping, or a token has the wrong field.Add or correct the mapping for the content type. Look at the URL preview: line.
The page numbers look wrong.Sibling Count has a value that is not a whole number.Clear Sibling Count, or enter a whole number.
An editor shows "No indexed collection found. Index your content first."The search index has no content.Speak to your team admin.
Last modified