Skip to content

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.

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.

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>.

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>

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 API - Low level components used on a search page and a category page

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.

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>

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>

Last update: January 22, 2021
×
Copyright

This online publication is intellectual property of Apptus Technologies. Its contents can be duplicated in part or whole, provided that a copyright label is visibly located on each copy and the copy is used in conjunction with the product described within this document.

All information found in these documents has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither Apptus Technologies nor the authors shall be held liable for possible errors or the consequences thereof.

Software and hardware descriptions cited in these documents might be registered trademarks. All trade names are subject to copyright restrictions and may be registered trademarks. Apptus Technologies essentially adheres to the manufacturer’s spelling. Names of products and trademarks appearing in this document, with or without specific notation, are likewise subject to trademark and trade protection laws and may thus fall under copyright restrictions.

CLOSE