Sitecore Experience Commerce

Using the commerce base themes

Abstract

Commerce base themes maintain the front-end logic (JavaScript) needed by the component, common services, third-party libraries, and framework.

Prior to the 9.0.3 release of Sitecore, JavaScript for commerce functionality was loaded using the AssetService pipeline. To improve performance and multi-site extensibility, all JavaScripts supporting commerce business functionality have been moved from files on disk to the sitecore/Media Library/Base Themes folder.

In this folder there are foundation themes along with commerce themes that contain scripts and styles to deliver more complicated functionalities. For example, shared functionalities such as the Bing/Google maps connector, Core Libraries (JQuery, lo-dash), and scripts that influence the editing experience (such as sticky notes, editing themes, drag and drop, and partial designs highlighting). 

You gain several advantages when scripts are moved from files on disk into themes. First, SXA processes the scripts, which bundles and minifies the content. This improves performance and transfer times. Second, every site can reference its own set of base themes.

The five available base themes maintain the front-end logic (JavaScript) needed by the component, common services, third-party libraries, and framework and are grouped into the following folders:

  • Commerce Core Libraries

  • Commerce Services Theme

  • Commerce Core Theme

  • Commerce Main Theme

  • Commerce Components Theme

Theme

Description

Commerce Core Libraries

This theme contains the third-party libraries used by Storefront components (such as KnockoutJS, jQuery, Bootstrap, and so on) Knockout is the main framework used in SXA Storefront for data binding.

Commerce Services Theme

This theme contains the shared services used by all Storefront components (such as the Ajax service used to handle the Ajax calls to the API). This theme also contains the communication and messaging logic between the components that follow the publisher-subscriber pattern.

Commerce Core Theme

This is the Foundation layer that contains the common JS logic used by all the components. It contains the application logic, component definition, and initialization.

Commerce Main Theme

This theme contains the main.js file that represents the entry point to the Storefront front-end application initialization.

Commerce Components Theme

This theme represents the Feature layer and it contains all the component-specific logic. Each Storefront component has its own JavaScript file named after the component that handles its initialization, data bindings, and some of the interactions between the user and the component.

Components that use the KnockoutJS view model have their own view model in a separate file (<component name>-model.js).

Important

The component-model file must be loaded before the corresponding component as the component has a dependency on the model.

The base themes are intricately related and must be loaded in the following order:

  1. Commerce Core Libraries

  2. Commerce Services Theme

  3. Commerce Core Theme

  4. Commerce Main Theme

  5. Commerce Components Theme

Warning

The loading sequence of the scripts is determined by the order of the scripts in the folder. It is very important that you do not change the order of the scripts.

The dependencies between themes is illustrated in the following figure.

ThemeDependency.png

To simplify customization, Sitecore has moved the content of the Storefront Branded theme into a new Storefront Branded Extension theme. The existing Storefront Branded theme is now empty and serves as a reference to the extension theme as well as base themes and core libraries.

ExtensionThemes.png

The new Storefront Branded Extension Theme requires the following scripts as displayed in the Selected list:

  • Basic2

  • Storefront Branded Extension

  • Commerce Core Libraries

  • Commerce Services Theme

  • Commerce Core Theme

  • Commerce Components Theme

  • Commerce Main Theme

Important

Do not change the order of the scripts. Doing so could result in storefront renderings not functioning correctly.

BrandedExtension.png

Important

To ensure that existing themes work with the new themes, you must follow the upgrade procedure  during which you are prompted to run the scripts available in the Commerce Experience Accelerator/Upgrade/Upgrade Scripts folder.