
[Part 5](http://jonnekats.nl/2019/implement-catalog-pages/) describes how to create a dynamic product page. This is great for navigating the catalog, but does not allow a content editor to select products to display on (e.g.) a landing page. This part presents how to create a product cluster component that enables displaying a configured set of products.


> JSS Commerce parts:
>
> - [part 1 - Exposing the Commerce Engine](http://jonnekats.nl/2019/exposing-the-commerce-engine/)
> - [part 2 - Navigating the catalog](http://jonnekats.nl/2019/navigating-the-catalog/)
> - [part 3 - Cart actions](/jss_cart_actions)
> - [part 4 - Tracking Cart events](/jss_tracking_commerce)
> - [part 5 - Implementing catalog pages](http://jonnekats.nl/2019/implement-catalog-pages/)
> - **[part 6 - Creating a product cluster](/jss_product_cluster)**
> - [part 7 - Conclusion](http://jonnekats.nl/2019/jss-commerce-conclusion/)

Let's first create a `ProductCluster` React JSS component;
```
import React from 'react';
import ProductList from '../../shared/components/productlist';

// ProductCluster displays products from the resolved datasource
const ProductCluster = ({fields}) => (
  <div className='productcluster'>
    <h1 className='productcluster__title'>{fields.heading}</h1>
    {<ProductList products={fields.products}/>}
  </div>
);

export default ProductCluster;
```
The component takes a heading text and products as `field` properties, and it re-uses the `ProductList` components that was introduced in [part 5](http://jonnekats.nl/2019/implement-catalog-pages/).

To enable a content editor to select the products to display we will use the Sitecore Query Builder.
In this way one can for example create a query for displaying all action products:

![](/jss_product_cluster_querybuilder.png)

The query can than be used on a page component, e.g. for listing action products on the home page:

![](/jss_product_cluster_selection.png)

Now we only need to create a list of products out of the query. For this we create a content resolver: `ProductsContentResolver`.
The `ProductsContentResolver` takes query selection field from the context item and performs a LinQ contentsearch query.
That's all, the complete code for the `ProductsContentResolver` is:

```
public class ProductsContentResolver : RenderingContentsResolver
{
    public override object ResolveContents(Sitecore.Mvc.Presentation.Rendering rendering, IRenderingConfiguration renderingConfig)
    {
        var contextItem = GetContextItem(rendering, renderingConfig);
        if (contextItem == null)
        {
            return new { };
        }

        var selectionField = (DatasourceField)contextItem.Fields[Templates.Products.Selection];

        var query = selectionField.Value;
        if (String.IsNullOrEmpty(query))
        {
            return new { };
        }

        var searchItems = new List<CommerceSellableItemSearchResultItem>();
        var searchManager = CommerceTypeLoader.CreateInstance<ICommerceSearchManager>();
        using (var context = searchManager.GetIndex().CreateSearchContext())
        {
            var searchStringModels = SearchStringModel.ParseDatasourceString(query);

            searchItems = LinqHelper.CreateQuery<CommerceSellableItemSearchResultItem>(context, searchStringModels)
                .Where(x => x.CommerceSearchItemType == CommerceSearchItemType.SellableItem)
                .Where(x => x.Language == Sitecore.Context.Language.Name)
                .ToList();
        }

        // Distinct products only as the products might exist at multiple places in the catalog
        searchItems = searchItems
            .GroupBy(x => x.ProductId)
            .Select(x => x.First())
            .ToList();

        // Create products from search result
        var products = new List<object>();
        foreach (var searchItem in searchItems)
        {
            var sitecoreItem = searchItem.GetItem();
            
            // Add variants
            if (sitecoreItem.HasChildren)
            {
                foreach (Sitecore.Data.Items.Item child in sitecoreItem.GetChildren())
                {
                    products.Add(GetProduct(searchItem, sitecoreItem, child.Name));
                }
            }
            // No variants add single product
            else
            {
                products.Add(GetProduct(searchItem, sitecoreItem));
            }
        }

        return new
        {
            Heading = ((TextField)contextItem.Fields[Templates.Products.Heading]).Value,
            Products = products.ToArray()
        };
    }

    private object GetProduct(CommerceSellableItemSearchResultItem searchItem, Sitecore.Data.Items.Item sitecoreItem, string variantId = null)
    {
        MultilistField field = sitecoreItem.Fields["Images"];
        var imageId = field.Items?.First();

        return new
        {
            searchItem.Path,
            searchItem.ProductId,
            searchItem.DisplayName,
            Description = sitecoreItem["Description"],
            ImageId = imageId,
            VariantId = variantId
        };
    }
}
```

After configuring the `ProductsContentResolver` as content resolver for the `ProductCluster` component and placing the `ProductCluster` on the home page, the product selection is show on the home page:

![](/jss_product_cluster_homepage.png)

Conclusion: the reusability of React components in combination with the configurability of JSS really shines for this use-case!


JSS Commerce part 6 - Creating a product cluster 🎽


In [part 3](/jss_cart_actions) of our JSS and Commerce series we have been adding cart actions. It would be great if we could track these using Sitecore Experience Analytics.
This article presents how we achieved tracking a *Lines Added To Cart* event using JSS, and describes the pros and cons of the chosen approach.


> JSS Commerce parts:
>
> - [part 1 - Exposing the Commerce Engine](http://jonnekats.nl/2019/exposing-the-commerce-engine/)
> - [part 2 - Navigating the catalog](http://jonnekats.nl/2019/navigating-the-catalog/)
> - [part 3 - Cart actions](/jss_cart_actions)
> - **[part 4 - Tracking Cart events](/jss_tracking_commerce)**
> - [part 5 - Implementing catalog pages](http://jonnekats.nl/2019/implement-catalog-pages/)
> - [part 6 - Creating a product cluster](/jss_product_cluster)
> - [part 7 - Conclusion](http://jonnekats.nl/2019/jss-commerce-conclusion/)


Remember that we decided to use Commerce Engine directly and thus have to add Analytics ourselves instead of the *normal* approach where the Commerce Connect layer handles analytics.

JSS ships with a tracking API that is pretty well described [here](https://jss.sitecore.com/docs/fundamentals/services/tracking).
To get started with JSS tracking, we enabled JSS tracking and [tracking of anonymous contacts](https://doc.sitecore.net/developers/xp/xconnect/xconnect-search-indexer/enable-anonymous-contact-indexing.html).

# Perform a page event tracking test
Next step is to test the out-of-the-box JSS tracking with a test event: 'Download'.
This is well described on the [documentation](https://jss.sitecore.com/docs/fundamentals/services/tracking) page, but currently it is missing the required fetcher and POST method in its description.

Below code snippet will get you started:
```
import { trackingApi } from '@sitecore-jss/sitecore-jss-tracking';
import { sitecoreApiHost, sitecoreApiKey } from '../temp/config';
import fetch from 'node-fetch';

const trackingApiOptions = {
  host: sitecoreApiHost,
  querystringParams: {
    sc_apikey: sitecoreApiKey,
  },
  fetcher: myFetcher
};

// Supply your own fetcher, see https://sitecore.stackexchange.com/questions/20929/jss-tracking-api-fetch-cors-and-mvc-errors/20931
async function myFetcher(url, data) {
    return await fetch(url, {
        method: 'post', 
        headers: {
            'Content-Type' : 'application/json'
        }, 
        body:  JSON.stringify(data)
    });
}

trackingApi
  .trackEvent([{ eventId: 'Download' }], trackingApiOptions)
  .then(() => console.log('Page event pushed'))
  .catch((error) => console.error(error));
```

# Hooking up Commerce events
Now that we have basic event tracking set up, it's time to hook up a Commerce event.
As use-case we want to track a *Lines Added To Cart* event. This event is normally triggered by Commerce Connect using the `TriggerCartLinesPageEvent` processor in the `commerce.carts.addCartLines` pipeline.

There are globally 3 places where we could plug in to track an event:

- IPageContext in Analytics Tracking
- Commerce Connect processor
- Commerce Connect pipeline <a id="option-3"></a>

The first option is to hook in at the Sitecore Analytics Tracking API, this means calling the `Register` on the `IPageContext` interface.
Internally the `TriggerCartLinesPageEvent` processor and JSS track event processors (like `TrackEvent`) use this.

Second option is to run a single Commerce Connect processor e.g. the `TriggerCartLinesPageEvent` processor.

The third option is to run an existing Commerce Connect pipeline e.g. `commerce.carts.addCartLines`. A Commerce Connect pipeline contains all required actions and analytics tracking for adding a cart line. As described in [part 3](./jss_cart_actions.md), we perform actions from the client. In order to make this option work, we would remove all non-analytics processors from the pipeline.

At first we tried hooking into the Analytics Tracking API as this is closest to the JSS implementation. This works, but it meant quite some reverse engineering of the Commerce Connect and Analytics processors.
We had to determine which cart & cart-line properties were used in several Commerce Connect & Analytics processors, this makes it error prone and hard to maintain, so we decided to abandon this approach.

Leaves us with the decision between plugging in at Commerce Connect pipeline or processor.
We decided to go for the processor as its interface is the same as the pipeline, and applying it for one processor would give us a impression of what it takes to implement for the complete pipeline.

## Creating a commerce event
All processors in the JSS `trackEvent` pipeline handle there own events. Events are parsed based on the specified class definition for each processor.
To track commerce events we created a new `CommerceEventInstance` class. This currently contains all properties that are necessary to track an *Lines Added To Cart* event. 

The code for the class looks like:
```
public class CommerceEventInstance
{
    public class CartLine
    {
        public string Product { get; set; }
        public decimal Price { get; set; }
        public string ProductName { get; set; }
        public decimal Quantity { get; set; }
    }

    public string CommerceEventId { get; set; }

    public string ShopName { get; set; }

    public List<CartLine> CartLines { get; set; }

    [JsonExtensionData]
    public IDictionary<string, object> AdditionalData { get; set; }
}
```
Note that used property names match Commerce Connect naming.


For the JSS client-side we create a small function that converts a cart line object into the required `CommerceEventInstance` structure:
```
async function trackCartlineEvent(id, line) {
  const lineEvent = {
    Product: line.itemId,
    Price: line.amount,
    ProductName: line.displayName,
    Quantity: line.quantity
  };

  trackingApi.trackEvent([{ commerceEventId: id, ShopName: shopName, CartLines: [lineEvent]}], trackingApiOptions);
}

export async function trackCartlineAdded(line) {
  trackCartlineEvent('Lines Added To Cart', line);
}
```

The `trackCartlineAdded` function can now easily be added to the `addCartLine` function in the `CartProvider` from [part 3](./jss_cart_actions.md):
```
async function addCartLine(token, line) {
    await commerceRequest.put('api/carts/me/addline', token, JSON.stringify(line));
    trackCartlineAdded(line);
}
```
At this point we have a JSS client-side application that can trigger Commerce *Lines Added To Cart* events. 
Now lets add a processor to the `trackEvent` pipeline that handles events with an `commerceEventId` property.

To implement a custom event tracker sub-class the abstract `MarketingDefinitionBasedEventProcessor` class, and implement the required methods:
```
public class TrackCommerceEvent : MarketingDefinitionBasedEventProcessor<CommerceEventInstance, IPageEventDefinition>
{
    protected override bool IsValidEvent(CommerceEventInstance eventInstance)
    {
        return !string.IsNullOrWhiteSpace(eventInstance.CommerceEventId);
    }

    protected override IPageEventDefinition ResolveDefinition(CommerceEventInstance eventInstance, TrackEventPipelineArgs args)
    {
        return this.GetDefinition(Sitecore.Analytics.Tracker.MarketingDefinitions.PageEvents, eventInstance.CommerceEventId);
    }

    protected override void DoTrack(IPageContext pageContext, IPageEventDefinition eventDefinition, CommerceEventInstance eventInstance)
    {
        var request = CreateCartLinesRequest(eventInstance);
        var result = new CartResult { Cart = request.Cart }; // Connect requires result cart to be filled.
        var args = new ServicePipelineArgs(request, result);

        // Trigger Commerce Connect Analytics processor
        var trigger = new TriggerCartLinesPageEvent()
        {
            Name = eventInstance.CommerceEventId,
            Text = eventInstance.CommerceEventId //Text equals id in practice, so for simplicity reuse it
        };
        trigger.Process(args);
    }
}
```
As you can see in above code, the only real logic is present in the `DoTrack` method. This is where we:

- parse the `eventInstance` into a `CartRequest`
- execute the `TriggerCartLinesPageEvent` processor

That's all! We have setup everything for tracking *Lines Added To Cart* events.
After adding two lines to the cart and visiting `/sitecore/api/jss/track/flush` we have all cart line events registered and visible at the xProfile page:

![](/jss_track_cartline_event.png)

# Conclusion
With limited effort we have implemented JSS based tracking for a single Commerce event.
This works pretty well from a JSS point of view. The challenge lies in connecting all line add/remove/update events but also all *Abandon Cart*, *Added To Cart Stock Status*, etc. events. We basically have to replicate the Commerce Connect pipelines in track event processors. This implies that for a full fledged implementation we probably best go for option #3 (from [here](#option-3)): re-using and calling a Commerce Connect pipeline.


JSS Commerce part 4 - Tracking Cart events 🛤️


Now that we have a catalog available (see [part 2](http://jonnekats.nl/2019/navigating-the-catalog/)) the next step is to add some cart actions: e.g. add and remove sellable items to/from a cart.
All cart actions follow the same design pattern. For simplicity this article presents only how to *add* a sellable item to a cart.


> JSS Commerce parts:
>
> - [part 1 - Exposing the Commerce Engine](http://jonnekats.nl/2019/exposing-the-commerce-engine/)
> - [part 2 - Navigating the catalog](http://jonnekats.nl/2019/navigating-the-catalog/)
> - **[part 3 - Cart actions](/jss_cart_actions)**
> - [part 4 - Tracking Cart events](/jss_tracking_commerce)
> - [part 5 - Implementing catalog pages](http://jonnekats.nl/2019/implement-catalog-pages/)
> - [part 6 - Creating a product cluster](/jss_product_cluster)
> - [part 7 - Conclusion](http://jonnekats.nl/2019/jss-commerce-conclusion/)

The steps to create a add cart line component are:

- Extend the API Gateway
- Create a Javascript client API
- Create a React Cart provider
- Create an Add to Cart button
- Use it

# Extend the Gateway
As we are using an API Gateway, see [part 1](http://jonnekats.nl/2019/exposing-the-commerce-engine/) for details, the first step is to expose an `addline` endpoint.
This new endpoint will expose the Commerce Engine `api/AddCartLine()` functionality. In order to add a cart line we need to provide a Cart identifier. This identifier is packed in the JWT.
So in the custom endpoint the Cart identifier is unpacked from the JWT and placed in the `api/AddCartLine()` request body.

The code snippet to add an `addline` endpoint to the API Gateway is:
```
config.ReRoute("/carts/me/addline")
    .Method(HttpMethod.Put)
    .To("https://commerce:5000/api/AddCartLine()")
    .TransformBody((_, httpContext, bytes) => SetCartIdInBody(httpContext, bytes)) // Simple method that gets Cart Id from JWT and adds it to the body
    .Method(HttpMethod.Put)
    .AuthenticateWith("<authenticationScheme>"); // JWT bearer authentication
```


# Create a Javascript client API
Next we want to create a Javascript client API that conveniently, e.g. handling some config, exposes a function call to add a sellable item to a cart.

## Request functions
To make the creation of a client API Gateway function call easier we created a small request module that abstracts HTTP requests. 
It injects some configuration variables, i.e. url and JWT token, and handles errors. Handling errors includes Commerce Engine errors which are special as the HTTP response code is 200, but the `ResponseCode` property may contain `Error` and the `Messages` property will contain descriptive error messages.

```
import fetch from 'node-fetch';
import { gatewayUrl } from '../../temp/config';

export async function put(uri, token, body) {
    let res = await fetch(`${gatewayUrl}/${uri}`, {
        method: 'put', 
        headers: {
            'Authorization' : `Bearer ${token}`, 
            'Content-Type' : 'application/json'
        }, 
        body: body
    });

    return handleErrors(res);
}

async function handleErrors(response) {
    if (!response.ok) { // Handle HTTP errors
        throw new Error(response.statusText);
    }

    const json = await response.json();
    if (json.ResponseCode === "Error") { // Handle Commerce Engine errors
        throw new CommerceError(json.Messages); // Maps Commerce Engine text errors to error messages
    }

    return json;
}

...
```

## Create add cart line function
We can now leverage the `request` module and create an *add cart line* call in one basically one line:
```
import commerceRequest from './request';

async function addCartLine(token, line) {
    await commerceRequest.put('api/carts/me/addline', token, JSON.stringify(line));
}
```

# Create a React Cart provider
In the above code you probably noticed that in addition to a cart line a token needs to be provided.
We want to retrieve this JWT token once and keep it in React state. Since React 16.8 there is a new way of handling state: using [React Hooks](https://reactjs.org/docs/hooks-reference.html).
In short, React Hooks allows us to use state in functional components by providing a Context, `useState`, and `useEffect` API.

## Authentication token provider
Let's have a look at how this works for storing our JWT token. First we will create an token context:
```
import React from 'react';

export const AuthContext = React.createContext();
```
> See [createContext](https://reactjs.org/docs/context.html#reactcreatecontext) for a full explanation on it.

Next we will use this context in our own `AuthProvider` component. Inside this component we use an effect (which is called once upon mount) to retrieve the token from the API Gateway, and use state to store the retrieved token. To make the token available in context of child components we use a Context Provider that sets the token value.

The code for the `AuthProvider` looks like:
```
async function getToken() {
    ... // Obtain token from API Gateway
}

export function AuthProvider({children}) {
    const [token, setToken] = useState(null);

    useEffect(() => {
        async function retrieveToken() {
            const token = await getToken();
            setToken(token);
        }

        retrieveToken();
    }, []);

    return (
        <AuthContext.Provider value={token}>
            {children}
        </AuthContext.Provider>
    );
}
```
> See [useState](https://reactjs.org/docs/hooks-state.html) and [useEffect](https://reactjs.org/docs/hooks-effect.html) for a more detailed explanation.


In order to make the token context available to all JSS components we add `AuthProvider` as wrapper in to the `AppRoot`.

## Cart provider
Now that we have the token available in context, we can use it to retrieve a cart and/or add lines to a cart.
To make the add to cart line function easy to use we decided to make a `CartProvider`. This provider will provide all cart data and actions, and will for example automatically refresh the cart after an mutation.

The code for the `CartProvider` looks very similar to the `AuthProvider`:
```
import { AuthContext } from './AuthProvider';

export const CartContext = React.createContext();

async function getCart(token) {
    return commerceRequest.get('api/carts/me', token);
}

async function addCartLine(token, line) {
    await commerceRequest.put('api/carts/me/addline', token, JSON.stringify(line));
}

async function refreshCart(token, onUpdateCart) {
    const cart = await getCart(token);
    onUpdateCart(cart);
    return cart;
}

export default function CartProvider({children}) {
    const token = useContext(AuthContext);
    const [cart, setCart] = useState(null);

    const actions = {
        addCartLine: async (line) => {
            await addCartLine(token, line);
            refreshCart(token, setCart);
        }
        ...
    };

    useEffect(() => {
        refreshCart(token, setCart);
    }, [token]);

    const cartContext = {
        data: cart,
        actions: actions
    };

    return (
        <CartContext.Provider value={cartContext}>
            {children}
        </CartContext.Provider>
    );
}
```
The only notable changes are:
- an Javascript Object that holds all Cart actions, and contains actions that e.g. refresh the cart after an update
- a token condition supplied to the `useEffect` which triggers a cart update when the `token` is refreshed


# Create an Add To Cart button
We can now create an *add to cart* button React component that uses the Cart context.

```
import React, {useContext} from 'react';
import { CartContext } from './CartProvider';
import { productCatalog } from '../../temp/config';

const AddToCartButton = ({productId, variantId, ...other}) => {
    const cart = useContext(CartContext);

    const sellableItem = {
        itemId: `${productCatalog}|${productId}|${variantId}`,
        quantity: 1,
        ...other
    };

    return (
        <button className='addtocart' onClick={() => cart.actions.addCartLine(sellableItem)}>
            Add to cart
        </button>
    );
}
```

# Use it
Last step is to actually use the button, for example by placing it on the `ProductSummary` React component which is used for displaying products on a product cluster.
As all required information is readily available on the `ProductSummary` component, adding the button is easy:
```
...

const ProductSummary = ({path, displayName, description, imageId, productId, variantId}) => {
    return <article className='productsummary'>
      <Title path={path} displayName={displayName} />
      <Description description={description} />
      <ProductImage imageId={imageId}/>
      <ProductPrice productId={productId} /> 
      <AddToCartButton productId={productId} variantId={variantId} displayName={displayName} /> 
    </article>
}
```

Finally this results in having a button on the page, for example:

![](/jss_product_summary.png)

Having a button that performs actions against the API Gateway and Commerce Engine obviously means that running in JSS disconnected is working, *but* only performs meaningful cart actions when the Gateway API and Commerce Engine are running. As the Commerce Engine requires a running Sitecore instance for its settings, this means that we actually need a fully running Sitecore XC setup for development. Which basically brings us to using JSS in integrated mode in practice.

# Conclusion
Creating a cart action component is, once the infrastructure components `request`, `AuthProvider` and `CartProvider` are in place, quick and easy!
By directly connecting to the Commerce Engine we can use the Commerce Engine domain models in Javascript and do not have an additional Commerce Connect Entity layer to understand and maintain.
For cart actions the only drawback is that we need to handle the Commerce Engine errors, which are not always user friendly, ourselves. 
For this POC we did not bother with transforming Commerce Engine errors, but for production usage this will be necessary. Last but not least, we need a running Sitecore XC setup for developing cart actions although JSS disconnected mode remains useful for client-side only development.


September 23, 2019

JSS Commerce part 6 - Creating a product cluster 🎽

September 19, 2019

JSS Commerce part 4 - Tracking Cart events 🛤️

September 18, 2019

JSS Commerce part 3 - Cart actions 🤸