Theming API V2¶

Apptus eSales Lifestyle is designed and themed out of the box in a way that follows many best practices in e-commerce. However, one design theme will not fit all sites. The Theming API v2 allow for easy customisation of several design elements used by the eSales Lifestyle components.

Overview¶

All theming customisations are provided via CSS custom properties and CSS shadow parts.

Theming of texts can be made on a broader level by setting the overall typography properties, affecting multiple components at once. This is recommended to be used primarily when altering the general typography, as it automatically provides consistency across the components.

Various other types of theming can be made by directly styling either the web components or their exposed parts and properties. This can also be used for very targeted typography styling when needed.

All custom properties are set on the :root. Only properties that differ from their default values should be specified.

:root {
  --ae-font-family: Roboto, Arial, sans-serif;
}

::part(breadcrumbs) {
  color: black;
  font-size: 14px;
  text-decoration: underline
}

::part(badge sale) {
  font-size: 12px;
  color: white;
  width: 22px;
  height: 22px;
  background: red;
  border-radius: 50%;
}

@media (max-width: 580px) {
  html { /* Note: html instead of :root */
    --ae-font-family: Roboto, Arial, sans-serif;
  }
}

Applying theming¶

By default, a stylesheet handling the look-and-feel for mobile usage is automatically applied for all web components. Custom theming can be built from scratch, but it is recommended that it is based off the default stylesheet as not to forget handling responsiveness for all parts.

Another recommendation is to provide all eSales component styling as a separate stylesheet, as this is beneficial from a performance perspective. Provided stylesheets should follow the requirements in the Shadow part shim section to enable the provided theming for older browsers.

The following step-by-step guide ensures that all best practices are followed:

1. Download the default stylesheet, available at https://cdn.esales.apptus.com/integration/v1/esales-lifestyle-responsive.css
2. Modify the stylesheet for the desired look-and-feel, following the specification in this section.
3. Host the CSS-file on your domain.
4. Make the CSS-file available to all pages on your site via:
   <link class="esales-lifestyle-stylesheet" rel="stylesheet" href="[filename].css">
   Note that the class esales-lifestyle-stylesheet is required.
5. Add disableResponsiveStyleSheet: true as a property to the script initialisation.
6. Success!

Typography¶

Typography properties will affect several components which is suitable for general, consistent text styling. If a specific component or part needs specific typography, styling can be adjusted through specific parts and properties.

All typography theming properties have a default value. Only properties that differ from their default values should be specified.

General¶

Affected parts and components¶

All parts and components, where not explicitly overridden by another value.

Headline¶

Affected parts and components¶

• Category title

Title¶

Affected parts and components¶

• Search header titles
• Recommendation titles

Label¶

Affected parts and components¶

• Facet header in facet modal
• Facet items

Body¶

Affected parts and components¶

• Facet chips
• Facet range values
• Facet select values
• Facet wrapper search text
• Navigation tree list items
• Navigation tree modal header
• Navigation assistant modal headers, tabs, and list items
• Preamble text
• Search assistant input field
• Search assistant phrase and content suggestions
• Search assistant recent searches

Body-2¶

Affected parts and components¶

• Facet colour values
• Facet select count
• Facet size values
• Navigation tree list item count
• Navigation page product count
• Product card sizes
• Search assistant subtitles
• Search header subtitles
• Search header count

Product title¶

Affected parts and components¶

• Product card product titles
• Product suggestion product titles

Product subtitle¶

Affected parts and components¶

• Product card product subtitles
• Product suggestion product subtitles

Parts and properties¶

All custom properties and exposed parts are grouped by the area or components that they affect. All custom properties are set on the root.

A part is a CSS pseudo-element that represents any element within a CSS shadow tree that has a matching part-attribute. Parts are styled in the same way as any regular HTML element, and can be used together with media queries other selectors as well as several pseudo-states. Parts natively support pseudo-states that considers the state of the part itself without dependencies to other elements, including:

:after
:before
:focus
:active
:hover

Some parts also have a set of additional states that are supported. State part support is found in the specification next to each part.

/* Basic part styling */
::part(facet-item) {
  background-color: teal;
}

/* Pseudo-state part support */
::part(facet-item):hover {
  background-color: pink;
}

/* State part support */
::part(facet-item open) {
  background-color: green;
}

/* Media query support */
@media (max-width: 1000px) {
  ::part(facet-item) {
     background-color: blue;
  }
}

/* Scoped part styling */
.spaced::part(facet-item) {
  margin: 12px;
}

For more information about CSS ::part(), see Mozilla Developer Network.

General¶

Breadcrumbs¶

Buttons¶

Badges¶

Category title¶

Facets¶

Facet item¶

Facet (select)¶

Facet (colour)¶

Facet (range)¶

Facet (size)¶

Facet chips¶

Favourites¶

Navigation tree¶

Product list¶

Product card¶

Preamble text¶

Ratings¶

Recommendations¶

Search assistant¶

Product suggestions¶

Search result¶

Search header¶

Sort by¶

Swatch¶

Custom font icons¶

The icons used in the web components can be customised by providing a URL to a .woff-file containing custom font glyphs. When providing custom font glyphs, all icons as specified below must be present in the file.

Step by step guide¶

1. Create the icons and save them in the SVG vector format. Do not use pixel based icons as they do not scale well.
2. Replace the icons. Make sure all 74 ligature icons are provided, e.g. only replace the ones that custom icons are provided for.
3. Create and host a .woff-file containing the custom icons. The creation of a .woff-file could for example be done using an application such as IcoMoon or any other suitable application. For applications that support loading icons as .json-files, the default icons can be loaded and viewed.
4. Provide the custom icons by initialising eSales with the parameter iconUrl pointing to the .woff-file. For more information, see Script Initialisation.

   // init-esales-lifestyle.js
   esales.init({
   ...
   iconUrl: 'https://cdn.esalesdrivensite.com/custom-icons.woff',
   ...
   });
   

5. Success!

Shadow part shim¶

As of June 2020, browsers facilitating roughly 70% of the global browser usage fully support CSS Shadow Parts. This includes the following browsers:

• Firefox 76+
• Chrome 81+
• Safari 13.1 (13.4 iOS)

To support older browsers, with partial or no built in support, a custom built shim is included in the JavaScript library. The shim ensures that the Theming API V2 is compliant with the general component library browser support, while allowing styling using CSS Shadow Parts.

Shim limitations¶

• Stylesheet resources using <link> must be decorated with the class esales-lifestyle-stylesheet, <link class="esales-lifestyle-stylesheet">.
• Stylesheet resources using <link> must be retrievable via fetch(), hence correct CORS headers must be applied if necessary. This is applicable if the resource is hosted on a separate domain, such as a CDN.
• Selectors above components are only evaluated when components re-render for performance reasons. For example, adding .active to the body will not take effect for the rule .active ::part(foo) until a component is re-rendered.