Gettings started with UI Framework

Download

To download the UI Framework, just run:

npm install @aurigma/ui-framework

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

If you don't want to install it locally, you can use jsdelivr CDN:

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

Load the editor on a page

Starting with UI Framework 4.0, you should load the editor to the page as follows:

<html>

<head>
  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
  <link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.1.0/css/bootstrap.min.css"
    integrity="sha384-9gVQ4dYFwwWSjIDZnLEWnxCjeSWFphJiwGPXr1jddIhOegiu1FwO5qRGvFXOdJZ4" crossorigin="anonymous">
  <style>
    .editor-container {
      padding-top: 16px;
    }
  </style>
</head>

<body>
  <div class="container-fluid">

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

    <script type="module">
      const uiFrameworkBaseUrl = "https://cdn.jsdelivr.net/npm/@aurigma/ui-framework@4.0.12";
      import moduleLoader from "https://cdn.jsdelivr.net/npm/@aurigma/ui-framework@4.0.12/dist/moduleLoader.js";
      document.addEventListener('DOMContentLoaded', async () => {

        // See https://customerscanvas.com/support/ui-framework/using-default-driver.md
        // for more details.
        const product = {
          id: 0,
          sku: "PRODUCT-001",
          title: "My Product",
          description: "This is a test product.",
          options: [],
          price: 1,
          attributes: []
        };

        // This is just a minimal "Hello World" configuration of UI Framework. 
        // See https://customerscanvas.com/support/ui-framework/readme.md for 
        // the syntax explanation and widget reference. 
        const config = {
          "showSteps": false,
          "widgets": [
            {
              "name": "text",
              "type": "static-text",
              "params": {
                "text": "Hello world"
              }
            }
          ],
          "steps": [
            {
              "name": "main",
              "mainPanel": {
                "name": "text"
              }
            }
          ]
        };

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

        let 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"));

        // How to receive data from the editor after the user finishes editing it
        ecommerce.cart.onSubmitted.subscribe(function (data) {
          console.log("submitted");
          data.lineItems.forEach(function (order) {
            console.log(order);
          })
        });
      
      });
        
      </script>
</body>

</html>

A few comments on this:

  1. Create a div element which will be a container for the editor.
  2. The editor is loaded to the page using the moduleLoader script which allows dynamically importing of ES6 modules.
  3. All modules are located from the location you configure with the uiFrameworkBaseUrl variable. Since the import keyword in JavaScript supports only string literals, you have to duplicate the URL there as well.
  4. There are two JSON object you have to prepare to pass to the editor - the product and the config. In this demo they are harcoded, however, in a real-life application you should either send them from back end or create dynamically.
    • The product contains a definition of the product from the ecommerce system. See the Working With E-commerce Driver article for details.
    • The config describes the user interface and the behavior of the editor. This sample illustrates the simplest possible config which does nothing for brevity. See the Introduction to UI Framework and other documentation articles to learn how to create more useful configs.
  5. You should load a couple of UI Framework modules (ecommerce driver and the editor) and initialize them using the driver.init(...) method where you pass product, config, and some other data. After that you are using the renderEditor method where you pass the container element you created on the step 1.
  6. To get the information from the editor when the user finishes editing, you can subscribe for the onSubmitted event handler. Other events also exist.