Partner Information
Becoming A Partner
Getting Started
POS Solutions
ERP Solutions
PIM Solutions
OMS Solutions
Marketing Solutions
Shipping Solutions
Payment Solutions
Provider APIs
Building Apps
Quick Start
Guide
Tutorials
Building Channels
Quick Start
Guide
Tutorials
new
Building Storefronts
Overview
Embedded Checkout
Managing Currencies
Guide

Widget Versioning Tutorial

This article documents how to use widget versioning to update a widget template without updating its widgets.

Prerequisites

Note

This tutorial uses Cornerstone theme.

Create a widget template

To create a widget template, send a POST request to v3/content/widget-templates.

POST /stores/{{store_hash}}/v3/content/widget-templates
Host: api.bigcommerce.com
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json

{
  "name": "Simple Text",
  "schema": [
    {
      "type": "tab",
      "label": "Content",
      "sections": [
        {
          "settings": [
            {
              "type": "text",
              "label": "Text Content",
              "id": "textContent",
              "typeMeta": {
                "maxLength": 1000
              }
            }
          ]
        }
      ]
    }
  ],
  "template": "<h1>{{textContent}}</h1>"
}

Open in Request Runner

Note

  • Make a note of uuid and current_version_uuid. We will use them in the steps that follow.

You can view your widget template in the store’s control panel using Page Builder, BigCommerce’s storefront editing and customization tool. You can locate your newly created widget template in the left pane under Custom.

Page Builder

Create a widget

In this tutorial, we will create and place our widget programmatically. To place your widget using Page Builder, drag and drop the widget template from the left pane onto the page.

To create a widget using the Widgets API, send a POST request to /v3/content/widgets. Replace the widget_template_uuid placeholder with the uuid from the previous step.

POST /stores/{{STORE_HASH}}/v3/content/widgets
Host: api.bigcommerce.com
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json

{
  "name": "Version 1 Widget",
  "widget_configuration": {
    "textContent": "Hello, World!"
  },
  "widget_template_uuid": "{your-widget-template-uuid}"
}

Open in Request Runner

Look for version_uuid and current_version_uuid in the response. You will notice that widget’s version_uuid matches current_version_uuid of the widget template.

{
  "data": {
    "channel_id": 1,
    "date_created": "2020-11-06T18:05:21.679Z",
    "date_modified": "2020-11-06T18:05:21.679Z",
    "description": "",
    "name": "Version 1 Widget",
    "uuid": "03ada835-fc01-4cf1-9c05-af86ee141cd5",
    "version_uuid": "5bb17ca3-a8c3-4a5a-bbf1-18a2b9ee9ddd", // value matches current_version_uuid
    "widget_configuration": {...},
    "widget_template": {
      "channel_id": 1,
      "client_rerender": false,
      "current_version_uuid": "5bb17ca3-a8c3-4a5a-bbf1-18a2b9ee9ddd", // value matches version_uuid
      "date_created": "2020-11-06T18:04:34.817Z",
      "date_modified": "2020-11-06T18:04:34.817Z",
      "icon_name": "default",
      "kind": "custom",
      "name": "Simple Text",
      "schema": [...],
      "template": "<h1>{{textContent}}</h1>",
      "uuid": "ee65e81f-a6a6-43a4-8d52-60bab87dbff3"
    }
  },
  "meta": {}
}

Place the widget

Place your widget by creating a placement. For this tutorial, we will place our widget in the home_below_featured_products region. To get a list of all available regions, send a GET request to v3/content/regions.

To place your widget, send a POST request to /v3/content/placements.

POST /stores/{{STORE_HASH}}/v3/content/placements
Host: api.bigcommerce.com
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json

{
  "widget_uuid": "{your-widget-uuid}",
  "entity_id": "",
  "template_file": "pages/home",
  "status": "active",
  "sort_order": 1,
  "region": "home_below_featured_products"
}

Open in Request Runner

The widget should now be visible on your store’s homepage under Featured Products.

Update the widget template

To create a new version of the widget template without affecting the widget created from it, we are going to include the "create_new_version": true parameter in the PUT request to /v3/content/widget-templates/{uuid}. This will create a new version record and associate that record to the current version.

POST /stores/{{store_hash}}v3/content/widget-templates/{uuid}
Host: api.bigcommerce.com
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json

{
  "name": "Red Text",
  "schema": [
    {
      "type": "tab",
      "label": "Content",
      "sections": [
        {
          "settings": [
            {
              "type": "text",
              "label": "Text Content",
              "id": "textContent",
              "typeMeta": {
                "maxLength": 1000
              }
            }
          ]
        }
      ]
    }
  ],
  "template": "<h1 style='color:red;'>{{textContent}}</h1>",
  "create_new_version": true
}

Open in Request Runner

Let’s look at our widget again. Send a GET request to /v3/content/widgets/{uuid} to retrieve your widget’s data. You will notice that current_version_uuid has changed and is now different from the widget’s version_uuid. Although we have updated the widget template, the widget created using that template did not change.

Create a new widget

All widgets created after the update will be based on the most current version. Let’s create another widget to test this functionality.

Send a POST request to /v3/content/widgets replacing the widget_template_uuid placeholder with your widget template uuid.

POST /stores/{{STORE_HASH}}/v3/content/widgets
Host: api.bigcommerce.com
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json

{
  "name": "Version 2 Widget",
  "widget_configuration": {
    "textContent": "Hello, World!"
  },
  "widget_template_uuid": "{your-widget-template-uuid}"
}

Open in Request Runner

To display the new widget next to the old one, place it in the same region. In our case, it is home_below_featured_products.

You should now see two different widgets displayed below Featured Products.

Add a new widget

Upgrade the widget

To upgrade the widget derived from the original widget template, send "upgrade":true in a PUT request to /v3/content/widgets/{uuid}. This will push the widget up to the latest widget template version.

Upgrade the widget

Note

  • If the newer version of your widget template contains different schema settings, you need to provide the necessary configuration values along with the upgrade flag to make sure the widget is updated correctly.

Related resources

Articles

Endpoints