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

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

Getting a quantity

{
  "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.

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

Working with options

There is a special widget called Option. 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.

{
    "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.

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