Extend components

Optimizely currently supports extensibility for cart, order, and subscription creation and editing in Commerce Connect 14.

The CSR extended components are added as extra views in CSR UI. There are three order types in CSR UI for these components to be added.

• Cart
• Order
• Subscription

In each order type, there are three locations that have the existing placeholder; this is where extended components are displayed.

• Header
• Footer
• Tab

These extended components are pre-built from ReactJS to CommonJS. After this extension package is installed, placeholders in the CSR UI read all necessary information for each component, such as order type, location, and the URL where the CommonJS code for this component is located. When the CSR application is running, it uses the URL to retrieve a CommonJS file for a specific component and loads it to the view at runtime.

Get started

CSR needs to know its extended components exist using ExtendedComponentOptions class. This class contains the information that a CSR needs to work with.

• Name – The display name of the component.
• ScriptUrl – The link of the pre-built component.
• Order – The displaying order on UI
• ComponentLocation – The location of the component. Using enum value.
  • Header = 0
  • Footer = 1
  • Tab = 2
• OrderTypes – The order types component applies to. Using flag enum value.
  • Cart = 1
  • PurchaseOrder = 2
  • Subscription = 4

Step 1: Configuration components' information

1. Create a class library project.
2. Create an InitializableModule class for this library and use ServiceConfigurationContext to add components.

context.Services.Configure<ExtendedComponentOptions>(x =>
    {
        x.ExtendedComponents.AddRange(new[]
        {
            Name = "CartOrderSubscriptionTab3",
            ScriptUrl = Paths.ToClientResource(GetType().Assembly, "clientResources/dist/CartOrderSubscriptionTab3/CartOrderSubscriptionTab3.js"),
            Order = 3,
            ComponentLocation = ComponentLocation.Tab,
            OrderTypes = OrderTypes.Cart | OrderTypes.PurchaseOrder | OrderTypes.Subscription
        });
    });

Step 2: Build React components

1. Configure a React Application in the class library project.
2. In src folder, create a folder, each folder will correspond to a component.
3. Create a component file that is built into a remote component.
4. Create an index file for local development to start webpack-dev-server and develop the component. Example: yarn dev:server --config-name config-CsrExtensionCartTab2

yarn dev:server --config-name config-{folder name of the component}

The localhost will run in port 9090.

5. After finishing development, run yarn build:release to generate a commonJS file of the component.
   Other commands

yarn build: debug => build in debug mode, mapping file will be generated for debugging.
yarn build: watch => build in debug mode, watch changes and re-build each changes.

Step 3: Add component's controller

For more complex usage, a controller should be created.

Create a folder in the root folder of the project. The folder name of the component should be the same as the one's folder in src folder (not mandatory, but for easy management).

Step 4: Pack the library project to nuget package

Run build.cmd to build the typescript and the solution.

Run pack.cmd to create the NuGet package.

An alternative way is to refer the site to the class library project.

Step 5: Run the commerce site

Run the commerce site, and the component is loaded at runtime.

Alternative

Instead of creating extended components in a separate module, the alternative way is to add pre-built component JS file to the web app (for example: put the JS file in the wwwroot folder)

Step 1: Config components' information

There are two ways to configure the web app.

• Using InitializableModule in the web app

context.Services.Configure<ExtendedComponentOptions>(x =>
    {
        x.ExtendedComponents.AddRange(new[]
        {
            Name = "CartOrderSubscriptionTab3",
            ScriptUrl = "/js/CartOrderSubscriptionTab3/CartOrderSubscriptionTab3.js",
            Order = 3,
            ComponentLocation = ComponentLocation.Tab,
            OrderTypes = OrderTypes.Cart | OrderTypes.PurchaseOrder | OrderTypes.Subscription
        });
    });

• Using appsettings.json

{
  ...
  "EPiServer": {
    ...
    "Commerce": {
      ...
      "ExtendedComponentOptions": {
        "ExtendedComponents": [
          {
            "Name": "CartOrderSubscriptionTab3",
            "ScriptUrl": "/js/CartOrderSubscriptionTab3/CartOrderSubscriptionTab3.js",
            "Order": 2,
            "ComponentLocation": 2,
            "OrderTypes": 7,
          }
        ]
      }
    },
    ...
}

OrderTypes uses flag enum, if a component belongs to more than one type, use the combination. For example: OrderTypes = 7 means this component belongs to Cart, PurchaseOrder, and Subscription.

Step 2: Build React components

1. Create a client app to build extended components to commonJS files.
2. Copy these files to the commerce site (for example: wwwroot folder).

Step 3: Add components' controller

Add controllers to the commerce site if necessary.

Usage example

https://github.com/episerver/commerce-csr-extensions