@aurigma/ui-framework/docs/working-with-ecommerce-driver.md

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

Working with the E-commerce Driver
==============================

When the editor is integrated with Shopify, WooCommerce, nopCommerce, or any other system, it is possible to create a config, which would interact with the e-commerce platform - by reading information about the product from the e-commerce product catalog, modifying the order, getting the price, etc. To make writing a single config for any system possible, all the code that works with a specific e-commerce system is isolated to a separate abstraction layer. We call it an _e-commerce driver_.

We won't get too deep into the details of how e-commerce drivers work and how to create your own. All you need to know at this point is that it is a JavaScript module that exposes objects like **Product**, **Order**, **Options**, **Attributes**, and **User**. All information about these entities is taken from an e-commerce system and passed to the editor through these objects.

It is recommended that you check out the [Integration with your e-commerce system using Default Driver](using-default-driver.md) topic to learn more about the integration and gain a better understanding of the entire system.

## How to access e-commerce driver data

After reading the articles about [Dynamic Configs](dynamic-configs.md), you should know that you can write some inline JavaScript code in the JSON config. You may be used to thinking that the only object you can access there is the `$` - array of widgets.

However, additional objects are available in the scope, in particular, `product` and `order` give you access to the information about the current product and the order.

The product contains such information as _attributes_ (some static details about the product) and _options_ (user choices).

The order contains a list of selected user choices, pricing, and quantity.

Let's examine a few examples.

### Reading a specific attribute value

This is a pretty common scenario where you want to read an attribute from a product and use it in the config. You can do it as follows:

``` json
{
    "designFile": "{{product.attributes.find(a=>a.title==='Template').value}}"
}
```

### Getting a quantity

``` json
{
  "type": "static-text",
  "name": "price",
  "params": {
    "text": "{{orders.current.quantity}}"
   } 
}
```

### Displaying a price

The price is available in two properties - `priceLocalized` (a formatted price as a string with the currency sign based on the e-commerce system cultural settings) and `price` (the price as a number).

This widget displays the price.

``` json
{
  "type": "static-text",
  "name": "price",
  "params": {
       "text": "{{'Total: ' + order.priceLocalized }}"
   } 
}
```

## Working with options

There is a special widget called [Option](widgets/option.md). It can grab the information about the option from the e-commerce system under the hood. All you need is to specify an `id` or `title` of the option, the same as the one that comes from the e-commerce system.

``` json
{
    "type": "option",
    "name": "product-style",
    "params": {
        "title": "Product Style"
    }
}
```
If the e-commerce driver contains an option called **Product Style**, it will automatically fill it with the appropriate values and other settings.

However, sometimes that is not enough. For example, if you want to bind the options from the e-commerce system to, say, designs or mockups in Customer's Canvas, you may want to merge the option definition from the e-commerce system with your own information.

In this case, you can just add your values by title and add extra information through the `props` property.

``` json
{
    "type": "option",
    "name": "product-style",
    "params": {
        "title": "Product Style",
        "values": [{
            "title": "Classic",
            "props": {
                "previewMockup": "mockup-classic"
            }
        },{
            "title": "Fancy",
            "props": {
                "previewMockup": "mockup-fancy"
            }
        }]
    }
}
```