Bloomreach Accelerator: B2C Commerce Application Libraries

Introduction

Bloomreach Accelerator: B2C Commerce provides out-of-the-box components and templates that cover typical commerce and content functionality. Components are extensible if needed, and templates are fully customizable and can be updated on-the-fly in a running instance.

Components and Templates

The table below lists the available components and links to their corresponding documentation pages. It also list, for each component, the corresponding Java classes and Freemarker frontend templates.

Some components are directly implemented as regular delivery components, others are implemented as command chain delivery components (see BRIEF Framework for more information). In the case of regular delivery components, the table lists the relevant component classes. These are packaged in com.bloomreach.commercedxp.starterstore.components. In the case of chain command delivery components, the table lists the relevant command classes which are used in conjunction with GenericCommandChainComponent. The command classes are packaged in com.bloomreach.commercedxp.starterstore.commands.

The templates listed in the table can be found in your Bloomreach Accelerator: B2C Commerce Boot project in repository-data/webfiles/src/main/resources/site/freemarker/hstdefault. They are deployed in the content repository as web files and can be updated on-the-fly via WebDAV.

Support for Commerce Connector SDK

From Bloomreach Accelerator: B2C Commerce 2.0, most of the components have been refactored to support the new Commerce Connector SDK.  As you can read on the Commerce Connector SDK detail page, Bloomreach Accelerator: B2C Commerce components can interact with repository implementations and deal with bean models instead of JSON resources. Those models are basically wrapping the response coming from e-commerce backends and offer a more standardized way to access information, the same approach used for content bean. For this reason, most of the Bloomreach Accelerator: B2C Commerce components have been adapted to support a more decoupled (and cleaner) approach.

Nevertheless, the v2 is still compatible with the previous commerce connector definitions, based on mapping bundles: please note that the old strategy is now deprecated and will be dropped in the next releases. Bloomreach Accelerator: B2C Commerce components can check if connectors are based on the Commerce Connectors SDK or not. You can re-use the logic adopted in the following snippet: 

@Override
public void doBeforeRender(final HstRequest request, final HstResponse response) {
    super.doBeforeRender(request, response);
    //obtain a decorated commerce connector instance 
    final CommerceConnector commerceConnector = getDecoratingCommerceConnector(request, response);
    if (StringUtils.isBlank(commerceConnector.getModuleName())) {
      //if the connector module name field is blank, then the commerce connector is compatible with v1
    }
    else {
      //if the connector module name field contains the HST addon module name, 
      //then the commerce connector is based on the Commerce Connector SDK and compatible with v2
    }
}

The new commerce connector definition available from v2 introduced a new field called "module name": this field can be used to check wheter the connector is based on v1 or v2.

Moreover, templates have been refactored accordingly. As you can read in the Commerce Connector SDK introduction page, Bloomreach Accelerator: B2C Commerce v2 drastically simplifies template development. Several bean models have been introduced and developers can directly use them: no need to extrapolate informations from JSON resources anymore.

The Bloomreach Accelerator: B2C Commerce Boot project, since it is backward compatible with v1, introduced new folders (identified with v1) under the repository-data/webfiles/src/main/resources/site/freemarker/hstdefault: those folders basically contain the old templates released with Bloomreach Accelerator: B2C Commerce v1. In order to select the "right" template while rendering pages, a fallback strategy has been introduced . As example, consider one of the Freemarker templates compatible with the Product Grid component, like starterstore-productlist.ftl.In Bloomreach Accelerator: B2C Commerce Boot v2 there are two templates:

• repository-data/webfiles/src/main/resources/site/freemarker/hstdefault/starterstore-productlist.ftl
• repository-data/webfiles/src/main/resources/site/freemarker/hstdefault/v1/starterstore-productlist.ftl

The Product Grid component in the Bloomreach Accelerator: B2C Commerce Boot references  to the first template, the one just below the hstdefault folder. A closer look at the new template definition will demonstrate how the template fallback works: 

<#if result??>
  //if the result is set, then fallback to the old template definition
  <#include "v1/starterstore-productlist.ftl" />
<#elseif beanResult??>
  //if the beanResult is defined, then fetch the relateed bean properties accordingly
  ..
</#if>

Bloomreach Accelerator: B2C Commerce components can include the result coming from the e-commerce backend in two ways:

1. Setting the result attribute,
2. Setting the beanResult attribute.

In case the result attribute has been set by the Bloomreach Accelerator: B2C Commerce component, then the commerce connector used is still based on v1: the object stored in the result attribute is a JSON resource that still needs to be processed in the templates. But, if the beanResult attribute has been set, then the commerce connector used is based on the Commerce Connector SDK. The beanResult attribute contains a commerce model mapping all the data: front-end developers just need to use the properties they need to display.

This hybrid approach must be considered as a temporary solution and will be refactored in the next releases, once the mapping bundles support will be entirely dropped. We advise to develop your templates based on CommerceModel  and more in general based on the Commerce Connector SDK.