@aurigma/ui-framework/docs/using-default-driver.md

A platform which allows building print product personalization editors based on Aurigma's Customer's Canvas.

Integration with your e-commerce system using Default Driver
==================================================



We have already created e-commerce driver modules, which work with our plugins for nopCommerce, Shopify, and WooCommerce. They make it possible to create configs that work in the same way in all systems.

However, these systems are not the only e-commerce apps available. So, you may wonder how to get the UI Framework seamlessly integrated with these 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 e-commerce driver objects described in our own JSON format and use several events to work with the e-commerce system. The following operations require interaction with the e-commerce 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 this can be done.

## Describing the product

If you examined the code from the [Getting Started article](getting-started.md), you noticed that, in the beginning, we declare a JSON structure like this:

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

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

The `id` is most 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 e-commerce 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](creating-parametrized-configs.md). It is just an array of values like this:

``` json
{
    ...
    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 is supposed to change, _options_ are the values selected by the user. For example, the paper type, product color, cutting options, etc. Each option may have a different price.

It looks like this:

``` json 
{
    ...
    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 the 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 e-commerce systems allows for editing them.

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` is mandatory and should be unique within one option.
- `title` is displayed in the editor and you can refer to it in the config.
- `price` is a price increment. In the example above, the `regular` paper type does not change the base price of a product, whereas the `kraft` paper type 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

You may often want to refer to 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:

``` json
{
    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:

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



## Initializing data in the UI Framework

After you have prepared the model of our product in the 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](getting-started.md), this code should already be familiar to you.

``` js
const uiFrameworkBaseUrl = "https://staticjs-aurigma.azureedge.net/ui-framework/latest";
import moduleLoader from "https://staticjs-aurigma.azureedge.net/ui-framework/latest/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}/drivers/default-driver.js`)).ecommerceDriver;
    
    const editor = (await moduleLoader.dynamicImportDefault("editor", `${uiFrameworkBaseUrl}/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 the main method, which you use to pass the product model as well as few other params from your system - a quantity and user information. This method returns an object that allows you to access 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 time to create an order in the e-commerce system.

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

```js
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 the 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` - lists of URLs of print files and proof images you want to associate with this line item (typically returned from Customer's Canvas through the **cart**/**order** widget).
- `data` - custom data passed through the **cart**/**order** widget. It is typically supposed to be saved along with the order.



This should be enough to make a basic integration with any e-commerce system. If your implementation requires additional assistance, please contact us at info@aurigma.com.