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

A BigCommerce store.
API access_token with content modify scope.
Knowledge of the Widgets API.

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.

You can add regions to templates in the templates/pages/ folder.
To edit theme files locally, use Stencil CLI.
To edit theme files in the control panel, use Page Builder.

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.

Example request: Get theme regions

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

Look for the region’s name in the response.

Example response: Get theme regions

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

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.

Example request: Create a widget template

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}}"
}

Response:

Example response: Create a widget template

{
  "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": {}
}

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.

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.

Example request: Create a widget

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}"
}

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`

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.

Example request: Create a widget placement

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"
}

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.

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

Custom Template 01

Add template content and a new region. (You can copy the content from category.html.)
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.

Example custom template

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

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/.

Example request: Create a category

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
}

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.

Example widget template

{
   "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":"#"
                        }
                     ]
                  }
               ]
            }
         ]
      }
   ]
}

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

Articles

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

A BigCommerce store.
API access_token with content modify scope.
Knowledge of the Widgets API.

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}}}

You can add regions to templates in the templates/pages/ folder.
To edit theme files locally, use Stencil CLI.
To edit theme files in the control panel, use Page Builder.

Verify region creation

Example request: Get theme regions

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

Look for the region’s name in the response.

Example response: Get theme regions

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

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.

Example request: Create a widget template

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}}"
}

Response:

Example response: Create a widget template

{
  "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": {}
}

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.

Example request: Create a widget

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}"
}

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`

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.

Example request: Create a widget placement

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"
}

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

Create a custom template placement

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

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

Custom Template 01

Add template content and a new region. (You can copy the content from category.html.)
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.

Example custom template

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

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/.

Example request: Create a category

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
}

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

Create a user interface

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

Example widget template

{
   "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":"#"
                        }
                     ]
                  }
               ]
            }
         ]
      }
   ]
}

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

Prerequisites

Create a region

Verify region creation

Create a widget template

Create a widget

Create a placement

Create a custom template placement

Create a user interface

Related resources

Articles

Prerequisites

Create a region

Verify region creation

Create a widget template

Create a widget

Create a placement

Create a custom template placement

Create a user interface

Related resources

Articles