Component API¶
The Component API have two levels of components that can be used for building pages, top level components and low level components. The top level components includes a set of functionality intended for a specific page type in a fixed design. The low level components are individual parts of the top level components, that can be used to compose pages with the same functionality but with a custom layout.
Top level components¶
Component | Description |
---|---|
Search assistant | A responsive search field with support for recent searches, phrase suggestions, product suggestions and more. |
Search results | A product listing with contextual filters, sorting, and headers for presenting a search result. |
Product page | A non-visible element indicating a product page for context purposes. It is used with the Recommendation component. |
Recommendation | A list of products displaying recommendations. Requires the Product page component. |
Navigation page | A product listing with contextual filters, sorting, and headers for presenting category listings. |
Navigation assistant trigger | A component that is used for navigation in mobile mode and interacts with the Navigation page component. |
Navigation assistant modal | A component that is used for navigation in mobile mode and interacts with the Navigation page component, with slot support. |
Recommendation product list | A component used to show recommendations on any landing page. |
Search assistant¶
The Search assistant component, <esales-search-assistant>
, is a search field that provides built in support for features such as recent searches, autocomplete, autocorrect, and product suggestions. The results will be shown in a pop-up next to the input field. At a certain breakpoint the component is instead rendered as a button (see --ae-mobile-width
). The button opens a modal for input on click, suitable for mobile devices.
Example¶
<esales-search-assistant placeholder="Search"></esales-search-assistant>
Attributes¶
Attribute | Type | Description |
---|---|---|
placeholder | string | Placeholder text for when the search input field is empty. |
Advanced¶
To build a custom Search assistant or to customise responsiveness, parts of the Search assistant component can be used separately, see Search assistant components.
Search results¶
The Search results component, <esales-search-results>
, is composed of a product listing and contextual filters. The content is determined by the search query and uses the URL query parameter q
of the current page to determine the result. Any changes to the sorting or facets will update the search result without a page load.
Example¶
<esales-search-results></esales-search-results>
Slots¶
The Search results component supports a slot for empty states, e.g content that is displayed when the query results in no hits.
<esales-search-results>
<div slot="no-search-hits">
<p>Feel free to check these sources for help.<p>
<ul>
<li><a href="/help-section">Help section</a></li>
<li><a href="/contact">Contact page</a></li>
</ul>
</div>
</esales-search-results>
Slot id | Description |
---|---|
no-search-hits | The content for this slot will be displayed when there are zero search results for the query. |
Product page¶
The Product page component, <esales-product-page>
, is a non-visible element indicating a product page that keeps track of notifications and visitor interactions. The attribute product-key
must be provided. For more information, see Product page integration.
Example¶
<esales-product-page product-key="P1"></esales-product-page>
Attributes¶
Attribute | Type | Description |
---|---|---|
product-key | string | The key of the product on the page. This key must match a product key provided in the data feed. |
Navigation page¶
The Navigation page component, <esales-navigation-page>
, contains the filters and product-listing. This component is not dependent on other components but is normally used in combination with the Category navigation component or the Navigation assistant component.
Example¶
<div class="wrapper">
<esales-navigation-tree></esales-navigation-tree>
<esales-navigation-page></esales-navigation-page>
</div>
The navigation components should be placed on all pages below a given path, e.g under all pages under https://example.com/categories/*
. The navigation components should also be placed on any old category page where the eSales Lifestyle category listings are to be used.
To test the Navigation page, make sure to have the navigationPagePathPrefix
properly set in the script initialisation. In the case above it would for example be https://example.com/categories
set as navigationPagePathPrefix
. Once in place, test the components by navigating to a URL where there is a mapped category in the taxonomy tree.
Navigation assistant¶
The top level component <esales-navigation-assistant>
has been deprecated and should be replaced by either <esales-navigation-assistant-trigger>
or if slot support is required, the <esales-navigation-assistant-modal>
.
Navigation assistant trigger¶
The Navigation assistant consists of a interactive trigger that opens a navigation assistant modal displaying the navigation. When adding the <esales-navigation-assistant-trigger>
, no explicit integration with the modal is needed as this is all handled through the trigger component.
Example¶
<header>
<esales-navigation-assistant-trigger></esales-navigation-assistant-trigger>
</header>
Navigation assistant modal¶
The Navigation assistant modal display the navigation and interacts with the Navigation page component that is used for listings for both desktop and mobile devices. The modal supports slots for custom content in two positions, and must be used with a custom trigger.
The categories displayed in the Navigation assistant modal are determined by the navigation configuration that has been set in the Navigation editor in the Experience app.
Attributes¶
Attribute | Type | Description |
---|---|---|
footer-fixed | boolean | True if the footer slot should have a fixed position at the bottom of the component. False if the footer should be positioned right after the navigational content. |
Slots¶
Slot | Description |
---|---|
header | The content for this slot will be displayed in the header in the navigation assistant modal. |
footer | The content for this slot will be displayed at the bottom in the navigation assistant modal. |
Examples¶
The example below shows a Navigation assistant modal with both slots set and a fixed footer.
<esales-navigation-assistant-modal footer-fixed="true">
<span slot="header">A slot header</span>
<span slot="footer">A slot footer</span>
</esales-navigation-assistant-modal>
The modal however is however likely initiated through a trigger. The example below illustrates how a modal with slots can be initiated from an HTML button using JavaScript.
<header>
<button class="modal-trigger">Open modal</button>
</header>
const btn = document.querySelector('.modal-trigger');
btn.addEventListener('click', function() {
// Create navigation assistant modal component
const modal = document.createElement('esales-navigation-assistant-modal');
// Create slot-content and add to modal
const slotEl = document.createElement('span');
slotEl.setAttribute('slot', 'header');
slotEl.textContent = 'Header slot';
modal.appendChild(slotEl);
// Create slot-content and add to modal
const slotEl2 = document.createElement('span');
slotEl2.setAttribute('slot', 'footer');
slotEl2.textContent = 'Footer slot!';
modal.appendChild(slotEl2);
// Optional - set the modal footer position to fixed.
modal.setAttribute('footer-fixed', true);
// Add modal to DOM
document.body.appendChild(modal);
})
Recommendation product list¶
The Recommendation product list component, <esales-recommendation-product-list>
, is a component that can be used to display various types of recommendations. Multiple algorithms for different purposes are available, and each recommendation can be restricted to a particular selection. The selection is determined by the provided facet attributes and can typically be used to create a highlight for particular product segments such as a new collection, a sale, or a specific subcategory.
The recommendation listing can either be presented as a carousel or a grid of products and can be used on any landing page such as the start page or an intermediate category page. Multiple recommendation listings can be added on the same page, but their zone-id
must differ.
Example¶
<esales-recommendation-product-list
zone-id="sp1"
size="8"
visualization="CAROUSEL"
breakpoint="1200"
data-custom.collection="SUMMER_COLLECTION"
label="Summer is here!"
show-more-link="https://www.esalesdrivensite.com/summer-is-here"
handpicked="P2,P4,P5,P7">
</esales-recommendation-product-list>
Attributes¶
Attribute | Description |
---|---|
zone-id | Zone Id, used to identify the specific zone. The zone Id is recommended to be related to the functionality and placement of the component. |
size | The amount of products that should be displayed within the zone. |
label | Label of the zone that is displayed in the top of the component. |
algorithm | The algorithm to rank and select the products. Can be set to either TOP_PRODUCTS , NEWEST_PRODUCTS , PERSONAL , CART , ALTERNATIVES , STYLE_WITH , UPSELL , or FAVORITES . Defaults to TOP_PRODUCTS if omitted. |
visualization | Optional attribute, modifies how product cards are displayed. Can be set to either CAROUSEL or GRID . Defaults to CAROUSEL if omitted. |
breakpoint | Optional attribute when using visualization="CAROUSEL" (or if the attribute is omitted). Defines the breakpoint in pixels when the carousel scroll arrows are either outside or inside of the carousel. The default value is 1050 . |
data-{attribute} | Is used to tell the component what filters should be applied. All standard attributes must be prefixed with data- . All custom attributes must be prefixed with data-custom. . The value must be a valid attribute value of the given attribute to be applied. The attribute and the attribute value must use the same format as in the data feed. Multiple values are separated with a pipe character, | , e.g. "Shorts|Pants" . Range values are enclosed within square brackets, [] , e.g. [0,100] . |
cart | Required if the algorithm is set to CART . The attribute should otherwise be omitted. A comma separated list of product keys, specifying the products in the cart, e.g. "P1,P2" . Provided product keys must match the format as provided in the data feed. |
product-key | Required if the algorithm is set to ALTERNATIVES , STYLE_WITH , or UPSELL , when the recommendation area is not on a product page. The attribute should otherwise be omitted. A product key to base recommendations on. The provided product key must match the format as provided in the data feed. |
handpicked | A comma separated list of product keys, specifying handpicked products to recommend, e.g. "P1,P2" . Provided product keys must match the format as provided in the data feed. |
show-more-link | Optional attribute, a link pointing to a page containing the full assortment of the recommendation selection as defined by the data attributes. Omitting this will prohibit the component from displaying a navigational text for displaying more products. |
show-more-label | Optional attribute, required if used in conjunction with show-more-link . Will be used as label for the show more link. |
Low level components¶
Component | Description |
---|---|
Search assistant components | Components that can be used to create a customised search assistance experience. |
Navigation tree | A navigation component that is used together with with product listing components, such as the Search results component, the Navigation page component, or the Primary product list component. |
Primary product list | A component displaying the primary product list that can be used together with the Facet list component, the Sort by component, the Category navigation component, and the Search header component. |
Facet list | A component for facets that is to be used with the Primary product list component. |
Sort by | A component for product sorting that is to be used with the Primary product list component. |
Search header | A component for explanatory search result texts including did-you-mean and autocorrect functionality that is to be used with the Primary product list component. |
Breadcrumbs | A component for providing the page breadcrumb that is to be used with the Primary product list component. |
Category title | A component for the category title that is to be used with the Primary product list component. |
Primary product count | A component used to show the resulting number of products and a configurable descriptive label, that is to be used with the Primary product list component. |
Preamble | A component used to show preamble text on a Navigation page. |
Search assistant components¶
The following components can be used to build a custom Search assistant.
Component | Description |
---|---|
Search assistant trigger <esales-search-assistant-trigger> | A button which on click opens a connected Search assistant modal. |
Search assistant input <esales-search-assistant-input> | A styled input field which presents suggestions in a connected Search assistant drop-down component. |
Search assistant drop-down <esales-search-assistant-dropdown> | A drop-down that presents suggestions. Can be connected to a custom input field. |
Search assistant modal <esales-search-assistant-modal> | A modal including an input field and search suggestions. Can be connected to a custom trigger. |
Search assistant result <esales-search-assistant-result> | The suggestion result, presented in both the Search assistant drop-down component and the Search assistant modal. Can be used to build a custom drop-down or modal. |
Navigation tree¶
The Navigation tree component, <esales-navigation-tree>
, is used to navigate between different categories and can be used with either the Navigation page component, the Search results component, or the Primary product list component`.
The content of the navigation tree is set up by using the Navigation editor in the Navigation tab in the Experience app.
Example¶
<div class="wrapper">
<esales-navigation-tree></esales-navigation-tree>
<esales-navigation-page></esales-navigation-page>
</div>
<div class="wrapper">
<esales-navigation-tree></esales-navigation-tree>
<esales-search-results></esales-search-results>
</div>
Attributes¶
Attribute | Description |
---|---|
search | Is used to tell the component if it should communicate with a search page instead of a navigation page. |
Primary product list¶
The Primary product list component, <esales-primary-product-list>
, is used to display the primary product listings that are the result of a search or the selection of a category page. It can be used to build a custom layout of a search result page or navigation page and works together with the Facet list component and the Sort by component, meaning filtering or sorting performed in those components will automatically be applied to the listing.
Example¶
<div class="wrapper">
<esales-facet-list></esales-facet-list>
<esales-facet-chip-list></esales-facet-chip-list>
<esales-sort-by></esales-sort-by>
</div>
<esales-primary-product-list></esales-primary-product-list>
Prefiltered lists¶
Apart from retaining the selection through search, or predefined settings from a category page, primary product lists can be prefiltered using facets. Facets that are used for prefiltering are automatically omitted and not be displayed in the Facet list component with selected values.
Example¶
<esales-primary-product-list data-custom.category_facet="Shorts|Pants" data-selling_price="[0,100]"></esales-primary-product-list>
Attributes¶
Attribute | Description |
---|---|
data-{attribute} | Is used to tell the component what filters should be applied. All standard attributes must be prefixed with data- . All custom attributes must be prefixed with data-custom. . The value must be a valid attribute value of the given attribute to be applied. The attribute and the attribute value must use the same format as in the data feed. Multiple values are separated with a pipe character, | , e.g. "Shorts|Pants" . Range values are enclosed within square brackets, [] , e.g. [0,100] . |
Facet list¶
The Facet list component, <esales-facet-list>
, is used for displaying facets which can be done either vertically or horizontally. The facets interacts with the Primary product list component that should exist on the same page. The facet chip list component also interacts with the facet list when added on the same page.
Example¶
<div class="wrapper">
<esales-facet-list></esales-facet-list>
<esales-facet-chip-list></esales-facet-chip-list>
<esales-sort-by></esales-sort-by>
</div>
<esales-primary-product-list></esales-primary-product-list>
<div class="wrapper">
<esales-facet-list vertical exploded></esales-facet-list>
<esales-primary-product-list></esales-primary-product-list>
</div>
Attributes¶
Attribute | Description |
---|---|
vertical | Will display the component vertically. Requires an additional attribute, either expandable or exploded . |
modal | The content of the component will be displayed in a modal that covers the entire screen, preferably used on mobile/tablet. |
expandable | The content of the component will appear in a box that expands in-between the facet title boxes. Used together with the attribute vertical . |
exploded | The content of the component will always be displayed and not hidden under a toggle. Used together with the attribute vertical . |
Facet chip list¶
The Facet chip list component, <esales-facet-chip-list>
, is used for displaying currently applied facets and allows users to remove them. The facet chip list interacts with the Facet list as well as the Primary product list component, that should exist on the same page.
Example¶
<div class="wrapper">
<esales-facet-list></esales-facet-list>
<esales-facet-chip-list></esales-facet-chip-list>
<esales-sort-by></esales-sort-by>
</div>
<esales-primary-product-list></esales-primary-product-list>
Sort by¶
The Sort by component, <esales-sort-by>
, is used for displaying the sorting selector. The sorting value interacts with the Primary product list component that must exist on the same page.
Example¶
<div class="wrapper">
<esales-facet-list></esales-facet-list>
<esales-facet-chip-list></esales-facet-chip-list>
<esales-sort-by></esales-sort-by>
</div>
<esales-primary-product-list></esales-primary-product-list>
Attributes¶
Attribute | Description |
---|---|
vertical | Will display the component vertically. Requires an additional attribute, either expandable or exploded . |
modal | The content of the component will be displayed in a modal that covers the entire screen, preferably used on mobile/tablet. |
expandable | The content of the sort by component will appear in a box that expands in-between the sorting title boxes. Used together with the attribute vertical . |
exploded | The content of the component will always be displayed and not hidden under a toggle. Used together with the attribute vertical . |
Search header¶
The Search header component, <esales-search-header>
, is used to display information related to a search query, such as product hits, and information related to autocorrect etc. Requires a search query parameter, q
.
Example¶
<div class="wrapper">
<esales-search-header></esales-search-header>
<esales-facet-list></esales-facet-list>
<esales-facet-chip-list></esales-facet-chip-list>
<esales-sort-by></esales-sort-by>
</div>
<esales-primary-product-list></esales-primary-product-list>
Breadcrumbs¶
The Breadcrumbs component, <esales-breadcrumbs>
, is used to display you navigation path. It will show the current steps of the navigation within the taxonomy-tree.
Example¶
<div class="wrapper">
<esales-breadcrumbs></esales-breadcrumbs>
<esales-facet-list></esales-facet-list>
<esales-facet-chip-list></esales-facet-chip-list>
<esales-sort-by></esales-sort-by>
</div>
<esales-navigation-tree></esales-navigation-tree>
<esales-primary-product-list></esales-primary-product-list>
Category title¶
The Category title component, <esales-category-title>
, is used to display the current selected category within the taxonomy-tree.
Example¶
<div class="header">
<esales-category-title></esales-category-title>
<esales-breadcrumbs></esales-breadcrumbs>
</div>
<div class="wrapper">
<esales-facet-list></esales-facet-list>
<esales-facet-chip-list></esales-facet-chip-list>
<esales-sort-by></esales-sort-by>
</div>
<esales-navigation-tree></esales-navigation-tree>
<esales-primary-product-list></esales-primary-product-list>
Primary product count¶
The Primary product count component, <esales-primary-product-count>
, is used to show the resulting number of products and a configurable descriptive label. It is to be used with the Primary product list component and is automatically updated by other low level components that are used together with the Primary product list such as the Facet list component.
Example¶
<div class="header">
<esales-category-title></esales-category-title>
<esales-breadcrumbs></esales-breadcrumbs>
</div>
<div class="wrapper">
<esales-primary-product-count></esales-primary-product-count>
<esales-facet-list></esales-facet-list>
<esales-facet-chip-list></esales-facet-chip-list>
<esales-sort-by></esales-sort-by>
</div>
<esales-navigation-tree></esales-navigation-tree>
<esales-primary-product-list></esales-primary-product-list>
Preamble¶
The Preamble component, <esales-preamble>
, is used to show preamble text on a Navigation page. Preamble text is set in the SEO section of a node in the Navigation tab of the Experience app.
Example¶
<div class="header">
<esales-category-title></esales-category-title>
<esales-breadcrumbs></esales-breadcrumbs>
<esales-preamble></esales-preamble>
</div>
<div class="wrapper">
<esales-facet-list></esales-facet-list>
<esales-facet-chip-list></esales-facet-chip-list>
<esales-sort-by></esales-sort-by>
</div>
<esales-navigation-tree></esales-navigation-tree>
<esales-primary-product-list></esales-primary-product-list>