Building Apps
Quick Start
Guide
Tutorials
Building Channels
Quick Start
Guide
Tutorials
Building Headless Storefronts
Guide
Embedded Checkout
Next.js Commerce
Building Checkouts
Managing Currencies
Guide
Partner Information
Becoming A Partner
Getting Started
Staying Current with Platform Changes
POS Solutions
ERP Solutions
PIM Solutions
OMS Solutions
Marketing Solutions
Shipping Solutions
Payment Solutions

Create and Place a Widget

BigCommerce’s Widgets API allows you to create, manage, and apply widgets to your storefront.

In this tutorial, you will create a widget (GitHub) that displays a row of three images and place that widget in a designated region on a category page of BigCommerce’s Cornerstone theme.

Prerequisites

To edit and preview theme files locally, we recommend using Stencil CLI, BigCommerce’s powerful theme development and deployment tool.

Create a region

For a widget to appear on a store’s page, you have to place it in a region. Regions are added and removed at the file level by editing a page’s template.

Let’s start by adding a new region called category_header_banner to your store’s category page template. You will use this region to position your widget later.

In templates/pages/category.html, add a new region {{{region name="category_header_banner"}}} below the page heading.

{{#unless theme_settings.hide_category_page_heading }}
    <h1 class="page-heading">{{category.name}}</h1>
    {{{region name="category_below_header"}}}
{{/unless}}
<!-- Add category_header_banner region -->
{{{region name="category_header_banner"}}}
<!-- End of Add category_header_banner region -->
{{{category.description}}}

If you are using Stencil CLI and editing theme files locally, run a stencil push command to apply your changes before proceeding to the next step. stencil push will bundle your theme into a zip file and upload the zip to BigCommerce. You can find more information on Stencil CLI commands in our Stencil CLI Option and Commands article.

Note

Verify region creation

To verify region creation, send a GET request to /v3/content/regions?template_file=pages/category. Make sure to specify the template_file=pages/category query string parameter to get the category template’s regions.

GET /stores/{{STORE_HASH}}/v3/content/regions?template_file=pages/category
Host: api.bigcommerce.com
X-Auth-Token: {{ACCESS_TOKEN}}
Accept: application/json

Open in Request Runner

Look for the region’s name in the response.

{
  "data": [
    {
      "name": "header_bottom"
    },
    {
      "name": "category_below_header"
    },
    {
      "name": "category_header_banner"
    }
  ],
  "meta": {}
}

Create a widget template

Widgets derive from widget templates. Before you can create a widget, you must first create its template. To do so, 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": "Header Images",
  "template": "{{#each images}}<a href='{{image_url}}'><img src={{image_source}} style='width:33.3%'/></a>{{/each}}"
}

Open in Request Runner

Response:

{
  "data": {
    "channel_id": 1,
    "client_rerender": false,
    "current_version_uuid": "c48b131a-ae9d-4767-b5d6-63d9e43bcf75",
    "date_created": "2020-11-03T18:51:22.877Z",
    "date_modified": "2020-11-03T18:51:22.877Z",
    "icon_name": "default",
    "kind": "custom",
    "name": "Header Images",
    "schema": [],
    "template": "{{#each images}}<a href='{{image_url}}'><img src={{image_source}} style='width:33.3%'/></a>{{/each}}",
    "uuid": "{your-widget-template-uuid}"
  },
  "meta": {}
}

Note

  • Make a note of the uuid of the widget template in the response. You will use it to create the widget in the next step.
  • Multiple widgets can use the same widget template.

Create a widget

To create a widget, use the widget template uuid from the previous step. Send a POST request to /v3/content/widgets making sure to replace the widget_template_uuid placeholder value with your template’s 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": "Header Images",
  "template": "{{#each images}}<a href='{{image_url}}'><img src={{image_source}} style='width:33.3%'/></a>{{/each}}",
  "widget_configuration": {
  	"images": [{
  	"image_source": "https://cdn11.bigcommerce.com/s-n0i50vy/images/stencil/1280x1280/products/109/361/kinfolkessentialissue_1024x1024__22507.1456436715.jpg?c=2&imbypass=on"
  	},
  	{
  	"image_source":"https://cdn11.bigcommerce.com/s-n0i50vy/images/stencil/500x659/products/85/282/livingwithplants_grande__26452.1456436666.jpg?c=2&imbypass=on"
  },
  {
  "image_source":
  	"https://cdn11.bigcommerce.com/s-n0i50vy/images/stencil/1280x1280/products/109/361/kinfolkessentialissue_1024x1024__22507.1456436715.jpg?c=2&imbypass=on"
	}
  ]
  },
  "widget_template_uuid":"{your-widget-template-uuid}"
}

Open in Request Runner

Property Description
name widget name displayed to user (required)
description widget description displayed to user (optional)
template widget’s template; overrides widget_template_uuid template
widget_configuration data for Handlebars context
widget_template_uuid default template uuid

Note

  • Make a note of the widget’s uuid in the response. You will use it to create a placement in the next step.

Create a placement

In the control panel UI, users can drag and drop widgets to place them in a region on a page. For this tutorial, we will use the Widgets API to place the widget programmatically.

To place your widget in the category_header_banner region of a category page, 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": "{your-category-id}",
  "sort_order": 1,
  "region": "category_header_banner",
  "template_file": "pages/category",
  "status": "active"
}

Open in Request Runner

Property Description
widget_uuid UUID of the widget
entity_id page, category, brand, or product ID
sort_order widget placement order
region region to place the widget in
template_file template file to target
status active or inactive

entity_id depends on the type of page; for example, for product pages, it is the product ID, and for category pages, it is the category ID. To place your widget on a specific category page, you need to provide a category ID. To retrieve available category IDs, send a GET request to /v3/catalog/categories. If you omit entity_id; the widget will appear on all category pages.

Create a custom template placement

It is possible to place a widget on a custom template. Just like with other pages, you must first add a region and then create a placement for your widget as described in Create a region and Create a placement steps, respectively.

In this section, you will create a custom category template which you can then use to place your widget.

  1. In the /templates/pages folder, create a /custom/category folder and add a custom-category.html file.

Custom Template 01

  1. Add template content and a new region. (You can copy the content from category.html.)

  2. Open the config.stencil.json file and update the custom-category.html property. The URL you define in config.stencil.json will be used for category mapping.

{
  "customLayouts": {
    "brand": {},
    "category": {
      "custom-category.html": "/custom-widget-templates/"
    },
    "page": {},
    "product": {}
  },
  "normalStoreUrl": "{STORE URL}",
  "port": "3000"
}

If using Stencil CLI, push and apply your changes.

  1. To create a new category using the Catalog API, send a POST request to /v3/catalog/categories. Use the URL defined in the config.stencil.json category mapping. In our example, it is /custom-widget-templates/.
POST /stores/{{store_hash}}/v3/catalog/categories
Host: api.bigcommerce.com
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json

{
  "custom_url": {
    "is_customized": false,
    "url": "/custom-widget-templates/"
  },
  "default_product_sort": "use_store_settings",
  "description": "<p>Custom category</p>",
  "is_visible": true,
  "layout_file": "custom-category.html",
  "name": "Custom Category",
  "sort_order": 1,
  "parent_id": 0
}

Open in Request Runner

  1. You can now create a placement for the widget you created in the previous steps.

Create a user interface

BigCommerce’s Page Builder tool allows you to customize different style elements of your theme in the store’s control panel. You can use Page Builder to configure and place widgets onto pages to tailor your storefront. To make your widget compatible with Page Builder, add custom configuration settings to the widget template by including the schema property in the create widget template request.

The following is an example of a widget template compatible with Page Builder.

{
   "name":"Header Images",
   "template":"{{#each images}}<a href='{{link}}'><img src={{imageUrl.src}} style='width:33.3%'/></a>{{/each}}",
   "schema":[
      {
         "type":"array",
         "label":"Images",
         "id":"images",
         "defaultCount":3,
         "entryLabel":"Image",
         "thumbnail":"imageUrl.src",
         "schema":[
            {
               "type":"tab",
               "label":"Content",
               "sections":[
                  {
                     "settings":[
                        {
                           "type":"imageManager",
                           "id":"imageUrl",
                           "default":{
                              "src":"https://cdn11.bigcommerce.com/s-n0i50vy/images/stencil/1280x1280/products/109/361/kinfolkessentialissue_1024x1024__22507.1456436715.jpg?c=2&imbypass=on",
                              "type":"IMAGE_MANAGER"
                           }
                        },
                        {
                           "label":"Link",
                           "type":"input",
                           "id":"link",
                           "default":"#"
                        }
                     ]
                  }
               ]
            }
         ]
      }
   ]
}

Open in Request Runner

To learn more about Page Builder, see Page Builder Overview.

Related resources

Articles