New online demos available.  

Integration with your ecommerce system using Default Driver

We have already created ecommerce driver modules which work with our plugins for nopCommerce, Shopify and WooCommerce. It makes it possible creating configs which works in the same way in all systems.

However, these systems are not the only ecommerce apps in the world. So you may wonder how to get the UI Framework seamlessly integrated with other systems?

The simplest way to do it is to use a Default Driver.

The idea of this driver is that you create all necessary ecommerce driver objects described in our own JSON format and use several events to works with the ecommerce system. The following operations require interaction with the ecommerce system:

  • Reading the information about the product being edited.
  • Submitting the order to the shopping cart.
  • Requesting the price for a specific combination of options.

Let's see how it can be done.

Describing the product

If you examined the code from the Getting Started article, you noticed that in the beginning we declare a JSON structure like this:

{
    id: 0,
    sku: "ABCD01",
    title: "My product",
    description: "...",
    price: 42,
    options: [],
    attributes: []
}

The sku, title and description are optional and can be filled only for debug purposes or if you want to use these somewhere in the config.

The id most is likely necessary when you are going to submit the order to the shopping cart.

The price is specified as a number, e.g. if a product costs $1.00, it will be 1, etc.

Attributes

Attributes are your product metadata in your ecommerce system. It is a good place to store a template file name, a size, etc. - the parameters you don't want the user to change.

The use of attributes is explained in the Creating Parametrized Configs article. It is just an array of values like this:

{
    ...
    attributes: [{
        "id": 0,
        "title": "MyAttrib",
        "value": "My value"
    }]
}

NOTE: You don't have to set id, but it is a good practice to have it, especially if the attribute names are not unique.

Option

While attributes are the parameters that the user are supposed to change, options are the values selected by the user. For example, a paper type, product color, cutting options, etc. Each option may have its price, etc.

It looks like this:

{
    ...
    options: [{
        "id": 0,
        "title": "Paper Type",
        "prompt": "A suggestion to the user what to change",
        "description": "Longer description hidden in a tooltip",
        "type": "radio",
        "values": [{
            "id": 1,
            "title": "Regular",
            "price": 0,
            "preselected": true
        }, {
            "id": 2,
            "title": "Kraft",
            "price": 1.5
        }]
    }]
}

Option properties

Unlike other items, id is important for both option itself and its values and it should be unique. It is necessary to get radio buttons and other list selections properly in HTML.

The title is how you are going to refer the option in the config.

The prompt and description are optional. Typically, the back end of most of ecommerce system allows editing it.

The type can be radio, list, image, color, etc. They are the same as supported by the option widget.

Option value structure

The structure of an OptionValue object is the following:

  • id - as mentioned above, it is mandatory and should be unique within one option.
  • title is displayed in the editor and you can refer it in the config.
  • price is a price increment. In the example above, a regular paper does not change the base price of a product, the kraft paper adds $1.5 to the price.
  • preselected means the default value of an option. Only one option value should have this property equal to true.

Extra properties for Color and Image options

If the option type is color or image, you may want to add the additional variables:

  • color - a color string in CSS format (like #fff or white or rgb(255,255,255)) which is used to visualize the option in a color list.
  • imageUrl - a URL to the image representing the option.

Custom data

It is often you want to refer some custom data in the option value. You may use the props property to associate an arbitrary object with this value. For example, we can set it as follows:

{
    options: [{
        ...
        title: "MyOption1",
        values: [{
            ...
            props: {
                "colorTheme": "MyTheme1",
                "designFile": "my-design-file"
            }
        }]
    }]
}

In the config, you create an option widget and use its selected value in another widget as follows:

{
    widgets: [{
        "name": "my-option",
        "type": "option",
        "params": {
            "title": "MyOption1"
        }
    }, {
        "name": "editor",
        "type": "canvas",
        "params": {
            ...
            "setTheme": "{{$['my-option']._.props.colorTheme}}"
        }
    }]
}

Initializing data in UI Framework

After you have prepared the model of our product in a correct form, it is a time to learn how to load the default editor and how to pass all the data into it.

If you read the Getting Started article, this code should be already familiar to you.

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 () => {

    const product = {
        /* Create it as explained above */
    };

    const config = {
        /* Create some config or download it from a server */
    };
    
    let initialQuantity = 1;

    // Load the default driver to your page. It is always distributed along with
    // the UI Framework in the drivers/default-driver.js file.
    const driver = (await moduleLoader.dynamicImport("ecommerceDriver", `${uiFrameworkBaseUrl}/dist/drivers/default-driver.js`)).ecommerceDriver;
    
    const editor = (await moduleLoader.dynamicImportDefault("editor", `${uiFrameworkBaseUrl}/dist/editor.js`)).editor;

    // Pass the product to this init method: 
    const ecommerce = await driver.init(product, editor, config, /* settings */ {customersCanvasBaseUrl: ""}, null, initialQuantity, /* user info*/ {id: 'test-user'});
    ecommerce.products.current.renderEditor(document.getElementById("editor-container"));

	... 
});

As you can see, the driver.init is a main method which you use to pass the product model as well as few other params from your system - a quantity and a user information. This method returns on object which allows you accessing the driver information - a product description, an order/cart, etc.

Submitting the product

When the user clicks the Finish button, the editing process is considered to be finished. It is a time to create an order in the ecommerce system.

To do it, after you initialize the editor, subscribe to the onSubmitted event:

const ecommerce = await driver.init(...);
ecommerce.products.current.renderEditor(document.getElementById("editor-container"));
ecommerce.cart.onSubmitted(data => {
    data.lineItems.forEach(lineItem => console.log(lineItem));
    /* implement your code submits the order to the shopping cart using this data */
});

The data object you receive contains an property lineItems which is an array of the objects with the following properties:

  • product - a Product object, the same as created during the initialization. Most likely, you will use its id to submit the shopping cart creation request to the server.
  • quantity - a quantity returned from the editor (you may change it through the cart/order widget).
  • choices - an array with the object containing the pairs of the options and their selected values.
  • downloadUrls and images - list of URLs of printfiles and proof images you want to associate with this line item (typically returned from Customer's Canvas through the cart/order widget).
  • data - a custom data passed through the cart/order widget. It is typically supposed to be saved along with the order.

It should be enough to make the basic integration with any ecommerce system. In case if you need anything special and need some help, please contact us at info@aurigma.com.