Search templates
The design part of each managed search configuration consists of three parts. Javascript that is executed on every page load, and CSS that is injected into the page. The JavaScript has the oppertunity to trigger an actual search. The search response can be rendered in HTML using the third part, a liquid template.
JavaScript
The JavaScript is executed on every page load. The JavaScript can import functionality from the available JavaScript modules.
When the pages JavaScript executes the following variables have been defined in the current scope.
| Variable | Description |
|---|---|
| key | The key of the search configuration |
| engine_options | Object containing options configured in My Hello Retail that should be used to determine how many items should be loaded for products and for each content type |
| config_id | The id of the current version of the search configuration. This is rarely used |
| $ | jQuery from helloretail.js if it has been loaded. jQuery is deprecated and only found on older templates |
| _ | The root object from helloretail.js (deprecated) |
CSS
The CSS template does not have any variables available in the liquid context. But the CSS template can define its own variables using the liquid assign syntax or the custom Hello Retail assign syntax explained in the introduction.
HTML
When implementing the HTML a large amount of variables are available in the liquid context. The variables in the root level will be described first. After that the more complex objects are described in their own section.
| Variable | Description |
|---|---|
| initialContent | List of Initial content / Zero Result content product sets and related metadata. See description below |
| products | An object containing two properties. totalResults which is the number of product results and results which is the list of products matching the search query. Each item is a product object. See description in the introduction |
| content | A map containing metadata and results from searching any configured content search engines. See description below |
| totalResults | Tne total number of search results across products and content |
| suggestedProductStatus | A value indicating if the product results are containing any results found using AI synonyms. It can have three values. NO_SUGGESTED indicating that non of the results were found using AI synonyms. MIXED indicating that some of the results were found using AI synonyms. ONLY_SUGGESTED indicating that all of the results were found using AI synonyms |
| query | The used search query |
| filters | The available filtering options that have been configured on My Hello Retail. See description below |
| sorting | The available sorting options that have been configured on My Hello Retail. See description below |
| redirects | The redirects matching the search query. See description below |
initialContent
Initial content is a list of sets of products that exist if initial content was requested or if there were zero search results. For the content to be loaded in those cases, it needs to be configured in My Hello Retail. It exists in the root context as initialContent. The content is a list of objects that each contain
| Variable | Description |
|---|---|
| title | Title for the content configured in the search configuration |
| subtitle | Subtitle for the content configured in the search configuration |
| count | Number of products returned in the initial content |
| products | List of products. Each item is a product object. See description in the introduction |
filters
A list of fields that are configured for filtering. For each field there are properties that can be used to build a UI for filtering product search results, also know as faceting.
There are three types of filters.
- List filters, where the user chooses one or more filters to apply. This could for instance be a list of brands
- Range filters, where the user chooses a numeric range to filter a field by. This is typically used for price filters
- A boolean filter. Just like a list filter, but there is only two options (true/false) and the displayed value is configured in the filter setup, so that the user can choose between "In stock" and "Out of stock", while the actual filter values are true and false.
The objects in the filters list have the following properties
| Variable | Description |
|---|---|
| title | The title of the filter configured in the configuration on My Hello Retail |
| name | The name of the field |
| isActive | Boolean that is true if the filter is currently being used, either by having an option selected or some range selected |
| exclusive | True if it is a boolean field |
| isRange | A boolean that is true if it is a range filter |
| min | Only for range filters. Minium available value |
| max | Only for range filters. Maximum available value |
| selectedMin | Only for range filters. If the range filter is active, this will contain the seleceted lower bound |
| selectedMax | Only for range filters. If the range filter is active, this will contain the selected upper bound |
| text | Only for boolean filters. Contains the text to use for the true option |
| negatedText | Only for boolean filters. Contains the text to use for the false option |
| selectedOptionCount | Only for list filters. The number of selected options for this filter |
| options | Only for list filters. Contains the list of available options for this filter. The items in the list is described below |
Each option in the options list in a list filter has the following properties
| Variable | Description |
|---|---|
| title | The text value of the option. Could be the actual brand |
| count | The number of products in the search result that has this value |
| query | The value to send in the search API request to apply this filter |
| selected | Boolean indicating if this filter was active in the API call that loaded these results |
| nestedTitle | Only available for hierarchy filters. It contains the last part of the hierarchy |
| depth | The number of levels in the hierarchy value |
sorting
A map of fields that are configured for sorting. For each field there are properties that can be used to build a UI for sorting product search results. These properties could for instance be used to add sorting to column headers in a table. It is possible to sort by more than one option at a time.
Each item in the map of sorting options contains the following properties:
| Field | Descripton |
|---|---|
| name | Field name the sorting option applies to |
| title | Title for the sorting option added in the configuration on My Hello Retail, like "Price" |
| ascText | Title for the ascending option, like "Prices ascending" |
| descText | Title for the descending option, like "Prices descending" |
| options | A list of options for sorting. Each item in the list has a title (the ascText or descText from above), a selected boolean indicating if this sorting option is currently selected and a query string that is what needs to be sent to the API to use this sorting option. |
The sorting also contains an options key. This key contains all the options from all the fields configured for sorting. This list is useful when building a single sorting dropdown that contains all the sorting options. It can also be used to build a list of currently applied sorting options.
redirects
A list of configured redirects that match the search query. Each item in the list contains the following properties
| Field | Descripton |
|---|---|
| title | Title of the redirect |
| url | Target URL of the redirect + a fragment containing the trackingCode. If helloretail.js is configured on a site and this fragment appears in the url, helloretail.js will automatically track a click on this redirect in a hello retail solution. Example: https://shop.example.com/categories/opening-hours/#aw_source=xx-asdasd-asdasd |
| originalUrl | URL of the redirect |
| trackingCode | Tracking code that can be sent to the /collect/click endpoint to track a click on this redirect in a Hello Retail solution |
content
Content is a map of the search results for each content type where a content search engine has been for set up for this search configuration.
There can be one entry for each type. The keys in the map are categories, sitePages, blogPosts and brands. Each entry is an object containing three properties. totalResults, options and results. totalResults is the total number of content items matching the search query for this content type. results contains a list of content objects matching the search query. Each content object reflect the data that is in the content catalog. They get their data from the configured content feeds. The content objects each have the following properties.
| Field | Descripton |
|---|---|
| title | Content title |
| imgUrl | URL of an image for the content |
| url | URL of the content + a fragment containing the trackingCode. If helloretail.js is configured on a site and this fragment appears in the url, helloretail.js will automatically track a click on this content in a hello retail solution. Example: https://shop.example.com/categories/shoes/#aw_source=xx-asdasd-asdasd |
| originalUrl | URL of the content |
| trackingCode | Tracking code that can be sent to the /collect/click endpoint to track a click on this content in a Hello Retail solution |
| description | Description of the content |
| keywords | Keywords of the content |
| hierarchy | A list strings reprecenting a hierarchy for the product (also referred to as a category or breadcrumb) |
| extraData | A dictionary of custom string attributes. Can be referred to as {{ item.extraData.x }} in the liquid templates. Where x is the name of the custom attribute |
| extraDataNumber | A dictionary of custom number attributes. Can be referred to as {{ item.extraDataNumber.x }} in the liquid templates. Where x is the name of the custom attribute |
| extraDataList | A dictionary of custom string list attributes. Can be referred to as {{ item.extraDataList.x }} in the liquid templates. Where x is the name of the custom attribute |
The options property contains texts that can be used to build a UI for the search results. These texts can be adjusted on My Hello Retail. The properties of the options object are
| Field | Descripton |
|---|---|
| title | Title configured for the content type |
| subtitle | Subtitle configured for the content type |
| type | String indicating the type of the content |
The Content Object
The content objects reflect the data that is in your content catalogs (Category, Brand, Blog Post, Site Page). You can have different types of content configured, each getting their data from a different content feed. The content types are identical except for their name.
Custom liquid filters
The search and pages templates have some custom liquid filters specifically for creating HTML suitable for being picked up by the register_filter JavaScript helper. These render filter values and sorting options from the filters or sorting liquid parameters. Typically an implementation will loop through the list of filters and output some UI for each of them.
asTagList
Works on list filters. Will output a list a <div> containing a <label> containing a <input> checkbox for each available filter option. The checkbox fill be checked if the filter option is selected.
Example
{{ filters[0] | asTagList }}
asDropdown
Works on list filters and on sorting options. Outputs a single <select> element with <option> for each available option. Any active filter/sorting option is marked as selected.
Example
This example will use the special options field on the sorting object to show a dropdown of all sorting options
{{ sorting | asDropdown }}
asList
Works on list filters. It is similar to the asTagList but has support for nesting for filter options that have the depth field available. Currently this is hierarchies.
It outputs a nested list of <ul> and <li> with <label> and <input> checkboxes inside.
{{ filters[0] | asList }}
asRange
Usable for range filters. Outputs a <span> containing a <span> holding the minimum value, a <span> containing the maximum value, and two <input> text fields containing the selected lower bound and the selected upper bound.
Default behaviour
In templates you can just output the filter object, and they will be rendered into HTML by default using one of the above liquid filters.
Range filters default to asRange
The hierarchies filter defaults to asList
All other filters default to asTagList