Integration with e-commerce systems
- 6 minutes to read
You can integrate UI Framework with e-commerce systems through drivers. We have already created e-commerce driver modules, which work with our plugins for nopCommerce, Shopify, WooCommerce, and Magento. 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, 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 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. 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 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:
{
...
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:
idis mandatory and should be unique within one option.titleis displayed in the editor and you can refer to it in the config.priceis a price increment. In the example above, theregularpaper type does not change the base price of a product, whereas thekraftpaper type adds $1.5 to the price.preselectedmeans the default value of an option. Only one option value should have this property equal totrue.
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#ffforwhiteorrgb(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:
{
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 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, this code should already be familiar to you.
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:
const ecommerce = await driver.init(...);
ecommerce.products.current.renderEditor(document.getElementById("editor-container"));
ecommerce.cart.onSubmitted.subscribe(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 itsidto 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.downloadUrlsandimages- 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.
Now, you can move to the next topic and learn how you can configure the key widget for personalizing print products.