Skip to content
×
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

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 A component that is used for navigation in mobile mode and interacts with the Navigation page component.
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. 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.
breakpoint number Specifies a breakpoint of the window width, where the search assistant toggles from an input field to an icon.

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.

Recommendation

The Recommendation component, <esales-recommendation>, is a product-listing of zones containing various recommendations based on the given algorithm-type. The recommendation component relies on a Product page component existing on the same page, see Product page integration. A Recommendation component can be either static or displayed as a product carousel.

Example

<esales-product-page product-key="P1"></esales-product-page>
<esales-recommendation zone-id="sp2" size="8" carousel breakpoint="1200" type="ALTERNATIVE" label="Similar items"></esales-recommendation>
<esales-recommendation zone-id="sp1" size="4" type="COMPLEMENTARY" label="You might also like"></esales-recommendation>

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 recommendation component.
size The amount of products that should be displayed within the zone.
type The algorithm-type of the zone. Can be either COMPLEMENTARY or ALTERNATIVE.
label Label of the zone that is displayed in the top of the component.
carousel Defines if recommended products should be displayed in a product carousel.
breakpoint Optional attribute when using the carousel attribute. Defines the breakpoint in pixels when the carousel scroll arrows are either outside or inside of the carousel. The default value is 1050.

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-category-navigation></esales-category-navigation>
  <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 Fashion 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 Navigation assistant component, <esales-navigation-assistant>, is used for navigation in mobile mode. It interacts with the Navigation page component that is used for listings in both desktop and mobile mode.

The categories displayed in the Navigation assistant component are determined by the taxonomy. The taxonomy is set up and altered using the Navigation editor in the Navigation tab in the Experience app.

Example

<header>
  <nav>...</nav>
  <esales-navigation-assistant></esales-navigation-assistant>
</header>

Slots

The Navigation assistant component supports slots for custom content in 3 positions. Slots can either be displayed on all subcategories or only main categories. This is controlled by the attribute sticky. The footer slot have an additional attribute, fixed, that can be either true or false.

Slot Sticky default Fixed default Description
header-top N/A N/A The content for this slot will be displayed at the top of navigation assistant on all departments.
header-bottom false N/A The content for this slot will be displayed below the header of the navigation assistant on all departments.
footer false false The content for this slot will be displayed at the bottom of navigation assistant on all departments.
Attribute Type Description
sticky boolean True if the slot should be visible on all subcategories.
fixed boolean True if the slot should have a fixed place at the bottom of the component.
Example
<header>
  <nav>...</nav>
  <esales-navigation-assistant>
    <span slot="header-top">Displayed above departments.</span>
    <span slot="header-bottom" sticky="true">Displayed right beneath departments.</span>
    <span slot="footer" fixed="true">Displayed at the bottom.</span>
  </esales-navigation-assistant>
</header>

Recommendation product list

The Recommendation product list component, <esales-recommendation-product-list>, is a generic recommendation component used to display the top products, personal recommendations or cart recommendations within a given 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"
    carousel
    breakpoint="1200"
    data-custom.collection="SUMMER_COLLECTION"
    label="Summer is here!"
    show-more-link="https://www.esalesdrivensite.com/summer-is-here">
</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, PERSONAL or CART. Defaults to TOP_PRODUCTS if omitted.
carousel Defines if recommended products should be displayed in a product carousel.
breakpoint Optional attribute when using the carousel attribute. 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].
algorithm Defines the algorithm to use for personal or cart recommendations. Can be either PERSONAL or CART.
cart Required if algorithm is set to CART, should be omitted otherwise.
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.
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.

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

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.

Category navigation

The Category navigation component, <esales-category-navigation>, is used to navigate between different categories and is used with either the Navigation page component, the Search results component, or the Primary product list component`.

The navigation tree which is displayed in the Category navigation component is set up by using the Navigation editor in the Navigation tab in the Experience app.

Example

<div class="wrapper">
  <esales-category-navigation></esales-category-navigation>
  <esales-navigation-page></esales-navigation-page>
</div>

<div class="wrapper">
  <esales-category-navigation search></esales-category-navigation>
  <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-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.

Example

<div class="wrapper">
  <esales-facet-list></esales-facet-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.

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-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-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-sort-by></esales-sort-by>
</div>

<esales-category-navigation></esales-category-navigation>
<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-sort-by></esales-sort-by>
</div>

<esales-category-navigation></esales-category-navigation>
<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-sort-by></esales-sort-by>
</div>

<esales-category-navigation></esales-category-navigation>
<esales-primary-product-list></esales-primary-product-list>

Last update: May 8, 2020