Getting Started

UI Framework Installation

There are two ways to enable the UI Framework on your server: install it locally and use it from a CDN (Content Delivery Network).

Downloading the Package

You can download and install the package @aurigma/ui-framework by using npm.

npm install @aurigma/ui-framework

This package is already compiled and bundled, there is no need to re-build it.

Using a CDN

If you don't want to install this package locally, you can use it from Azure CDN:

https://staticjs-aurigma.azureedge.net/ui-framework/latest

Loading the Multi-Step Editor on a Page

Now, let's see how you can use the UI Framework in your application.

First, you must specify a DIV element which will be a container for the editor.

<div id="editor-container" class="editor-container">
</div>

The editor is loaded to the page by using the moduleLoader script, which allows you to dynamically import ES6 modules. You can import the locally installed moduleLoader as follows:

import moduleLoader from "./node_modules/@aurigma/ui-framework/dist/moduleLoader.js";
const uiFrameworkBaseUrl = "./node_modules/@aurigma/ui-framework/dist";

You can use a variable for the location of modules, for example, uiFrameworkBaseUrl. Since the import keyword in JavaScript supports only string literals, you have to duplicate this URL there as well.

As an alternative, you can import the moduleLoader from Azure CDN:

import moduleLoader from "https://staticjs-aurigma.azureedge.net/ui-framework/latest/moduleLoader.js";
const uiFrameworkBaseUrl = "https://staticjs-aurigma.azureedge.net/ui-framework/latest";

Providing an Editor Configuration

There are two JSON objects that you have to pass to the editor: a product and a config.

The product object contains a definition of a product from your e-commerce system. You can refer to the Working with e-commerce driver↗ topic for details.

const product = {
  id: 0,
  sku: "PRODUCT-001",
  name: "My Product",
  description: "This is a test product.",
  options: [],
  price: 1,
  attributes: []
};

The config describes the user interface and the behavior of the editor. The following example illustrates the simplest possible config, which has no real useful function but keeps the explanation brief. You can refer to the Introduction to the UI Framework↗ and other documentation articles to learn how to create more useful configs.

const config = {
  "showSteps": false,
  "widgets": [
    {
      "name": "hello",
      "type": "static-text",
      "params": {
        "text": "Hello world!"
      }
    }
  ],
  "steps": [
    {
      "name": "main",
      "mainPanel": {
        "name": "hello"
      }
    }
  ]
};

In these examples, we hardcode the product and config. In a real-life application, you should send the product object from the back end and create the editor config dynamically.

Initializing an E-commerce Driver

After you have defined a product and a config, you should load an e-commerce driver and the editor modules and initialize them by using the driver.init method where you pass the product, config, and other data. After that, you can call the renderEditor to place the editor into the editor-container.

const driver = (await moduleLoader.dynamicImport("ecommerceDriver", `${uiFrameworkBaseUrl}/drivers/default-driver.js`)).ecommerceDriver;
const editor = (await moduleLoader.dynamicImportDefault("editor", `${uiFrameworkBaseUrl}/editor.js`)).editor;

const ecommerce = await driver.init(product, editor, config, /* settings */ { customersCanvasBaseUrl: "" },
                  /* restore data */ null, /*quantity*/ 1, /* user info*/ { id: 'test-user' });
ecommerce.products.current.renderEditor(document.getElementById("editor-container"));

Now, if you open the resulting page in a browser, you can see the running multi-step editor.

Using the Design Editor

To enable the Design Editor, you need a working instance of Customer's Canvas. If you still do not have a Customer's Canvas license key, you can request a trial license valid for the 30-day evaluation period as described in the Evaluating Customer's Canvas topic.

In the driver settings, you must specify the URL linking to this instance, for example:

const settings = { customersCanvasBaseUrl: "https://example.com:44300/" };
const ecommerce = await driver.init(product, editor, config, settings, null, 1, { id: 'test-user' });

After that, you must configure the design-editor widget. The following example illustrates how you can open the Design Editor in the Main Panel and initialize it with the postcard.psd template.

const config = {
  "widgets": [
    {
      "name": "editor",
      "type": "design-editor",
      "params": {  
        "initial": {  
          "productDefinition": { 
            "surfaces": ["postcard"] 
          }
        }
      }
    }
  ],
  "steps": [
    {
      "name": "main",
      "mainPanel": {
        "name": "editor"
      }
    }
  ]
};

Receiving Data from the Editor

When the user clicks the Finish button, the editing process is considered to be finished. It is time to create an order in the e-commerce system. To get the information from the editor, you can subscribe to the onSubmitted event handler.

ecommerce.cart.onSubmitted.subscribe(function (data) {
  console.log("submitted");
  data.lineItems.forEach(function (order) {
    console.log(order);
  })
});

ASP.NET-based Demo

If you want to implement an ASP.NET Core application that uses the UI Framework, you can look at a working sample in the following GitHub repository:

UI Framework Sample↗

This project demonstrates how you can implement a multi-step editor to personalize print products.

See Also

Manual

• Integration with E-commerce Overview
• UI Framework tutorials↗
• Working with e-commerce driver↗

Downloads

• Code sample