TrophyCustomer's Canvas is honored with a 2020 InterTech Technology Award! Learn more 

Getting Started

The UI Framework represents a series of JavaScript applications, which allows you to integrate a multi-step editor to personalize and order your products. This topic describes how you can initialize and load the multi-step editor, enable the Design Editor, and obtain resulting data.

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 or jsDelivr CDN:

  • Azure CDN

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

  • jsDelivr CDN

    https://www.jsdelivr.com/package/npm/@aurigma/ui-framework

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.

HTML
<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:

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

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 either Azure or jsDelivr CDN:

  • Azure CDN

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

    import moduleLoader from "https://cdn.jsdelivr.net/npm/@aurigma/ui-framework@4.6.1/dist/moduleLoader.js";
    const uiFrameworkBaseUrl = "https://cdn.jsdelivr.net/npm/@aurigma/ui-framework@4.6.1/dist";
    

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.

JavaScript
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.

JavaScript
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.

JavaScript
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:

JavaScript
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.

JavaScript
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.

JavaScript
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

Downloads