Lab - Create a Widget Template for Static Content

Summary

Page Builder enables non-technical users to create and edit site content with a drag-and-drop visual editing tool, no code required. Out of the box, BigCommerce provides several commonly used content blocks, or widgets templates, that can be used to construct entire pages or inject content into existing pages like Product or Category pages. But merchants are not limited to using the widget templates provided by BigCommerce. Developers can create custom widget templates to meet specific use cases.

Throughout this guide, you will create widget templates with increasing levels of complexity. In this section, you will create a simple template that adds static content to a page. In later sections, you make a new template that you can populate with information from your BigCommerce catalog, and finally you will create a widget template that provides a single “add to cart” button for multiple products.

In this lab you will

• Write a widget template schema with
  • an input for some heading text
  • an image manager input to select an image
  • a range slider to configure the image width
  • and a text input for some copy to display beneath the image
• Create the widget template
• Create a widget with the new widget template

Prerequisites

• A BigCommerce Store
• A Stencil theme with at least one region
• A REST client like Postman
• A BigCommerce API Key with the Modify Content scope

Create a Content Widget

This lab primarily focuses on creating widget templates, but before creating the widget it’s helpful to explore the relationships between:

• regions
• widget templates
• widgets
• and placements

Regions are areas on the storefront where widgets may be placed. Regions are defined in the Stencil theme’s HTML template files. For example, the Cornerstone theme includes several regions in the home.html template file like this one. Regions with a name that ends in “—global” , like this one in header.html, are considered global regions. That means that any widgets placed in the global region will appear on every storefront page that includes that region. Widgets placed in non-global regions will only render on the specific page where the widget was placed such as a specific product page, category page, content page, or the home page.

In Page Builder, global regions appear as a purple color while other regions appear as a blue color.

Widget templates define a schema with JSON and use HTML and Handlebars to render content. All of the items in the left sidebar in the image above, with the exception of Layout, are widget templates. When you drag a widget template into a region in Page Builder to create a widget, the configurable settings in the widget schema are exposed in the left sidebar. The schema settings can be configured by the content creator to change the content or behavior of the widget. For example, the screenshot below shows how content creators can configure settings using inputs like a text field, color selector, or image upload.

When you drag a widget template into a region, configure the settings, save and publish it, BigCommerce creates a widget and a placement. The widget is an instance of the widget template and the placement defines the region, template file, and entity ID (product/category/brand/web page id) in relation to the widget.

Write the Widget Template Schema

The widget template’s schema defines the inputs a content creator can use to configure a widget. Widget templates use Handlebars to access the configured values to determine the content, markup, and styles to display.

In this section, you will write a schema containing:

• a text input to enter Heading Text
• an image to display under the heading
• a slider to set the width of the image
• a text field to display content below the image

Throughout this section, you will write HTML and JSON to create the request body for a Create a Widget Template POST request. You may reference the following code sample during the following steps to check your work: Code Sample

1. In your text editor, write JSON for an array by typing [ ]:
2. In the array, add the following object:

{
    "type": "tab",
    "label": "Static Content",
    "sections": []
}

3. Add a section object with a label string and an empty settings array to the sections array. Example:

{
    "type": "tab",
    "label": "Static Content",
    "sections": [
        {
            "label": "Static Content",
            "settings": []
        }
    ]
}

4. In the settings array, add an Input setting. This setting’s value will be used as the text in a heading element, so the default text and the label should reflect that usage.

{
    "type": "input",
    "id": "heading_text",
    "label": "Heading Text",
    "default": "Type a Heading"
}

5. In the settings array, add an Image Manager setting. This setting’s value will be used as the src attribute for an img tag, so the default image source and the label should reflect that usage.

{
    "type": "imageManager",
    "id": "image",
    "label": "Image",
    "default": {
        "src": "https://placehold.it/250x250",
        "type": "IMAGE_MANAGER"
    }
}

6. In the settings array, add a Range setting. This setting’s value will be used as the width attribute for an img tag, so the default value, min/max, units, and the label should reflect that usage.

{
    "type": "range",
    "label": "Image Width",
    "id": "width",
    "default": "250",
    "typeMeta": {
        "rangeValues": {
            "min": 100,
            "max": 1200,
            "step": 1,
            "unit": "px"
        }
    }
}

7. In the settings array, add a Text setting. This setting’s value will be used to populate copy beneath the image, so the default value and the label should reflect that usage.

{
    "type": "text",
    "label": "Text Block Content",
    "id": "text_block",
    "default": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed pellentesque tortor ante, id maximus massa volutpat et. Aliquam at leo a purus condimentum tristique. Nulla feugiat enim quis neque suscipit, sed dictum quam tempor. Morbi purus metus, porta tincidunt justo eget, mollis volutpat justo. Suspendisse enim est, tristique vel nisl in, facilisis aliquam risus. Nunc placerat quam quam, eget blandit augue finibus sed. Donec in facilisis urna, eu egestas diam. Maecenas consequat a lacus et pharetra. Nullam sodales mi sed libero venenatis placerat. Proin quis pharetra metus. Suspendisse elementum at libero nec dignissim. In convallis imperdiet turpis eget hendrerit. Quisque sapien enim, vestibulum vitae ullamcorper et, rutrum faucibus nunc."
}

At this point, your schema should contain the same settings the schema array in this example.

Write the Widget Template Markup

While the widget template schema is used to define the user inputs and configurable values, the template’s markup will be used to define the structure and styling of the widget. Widgets access schema values by referencing the schema setting’s id in Handlebars. For example, to reference the text entered into the input with an id of “heading_text”, the following Handlebars expression will be used:

{{heading_text}}

In the case of input settings, the value referenced by their ID is a string. But, more complex settings like an imageManager may return other values, such as an object. In the case of the imageManager, you can use the following Handlebars expression to reference the src property of the value returned by a setting with an id of “image”:

{{image.src}}

In the following steps, you will create a basic template using HTML and Handlebars to reference the values supplied by the user. After writing the HTML, you will use a tool to properly escape the HTML for use in a JSON request body. In the end, you should have something like the template property in the example here.

1. In a text editor of your choice, write an H2 tag containing the heading_text schema setting value. Example:

<h2>{{heading_text}}</h2>

2. Add an IMG tag with the src attribute set to the image.src schema setting value and the width attribute set to the width schema setting value. Example:

<img src="{{image.src}}" width="{{width}}" />

3. Add a DIV tag containing the text_block schema setting value. Example:

<div>{{text_block}}</div>

You should now have 3 lines of HTML:

<h2>{{heading_text}}</h2>
<img src="{{image.src}}" width="{{width}}" />
<div>{{text_block}}</div>

4. Use a JSON escaping tool like codebeautify.org to convert the quotation marks and line breaks into escaped characters resulting in a single line of code.

At this point, you should have a line of code that matches the template in the example:

{
	"name": "Static Image + Content",
	"schema": [
        {
            "type": "tab",
            "label": "Static Content",
            "sections": [
                {
                    "label": "Static Content",
                    "settings": [
                        {
                            "type": "input",
                            "id": "heading_text",
                            "label": "Heading Text",
                            "default": "Type a Heading"
                        },
                        {
                            "type": "imageManager",
                            "id": "image",
                            "label": "Image",
                            "default": {
                                "src": "https://placehold.it/250x250",
                                "type": "IMAGE_MANAGER"
                            }
                        },
                        {
                            "type": "range",
                            "label": "Image Width",
                            "id": "width",
                            "default": "250",
                            "typeMeta": {
                                "rangeValues": {
                                    "min": 100,
                                    "max": 1200,
                                    "step": 1,
                                    "unit": "px"
                                }
                            }
                        },
                        {
                            "type": "text",
                            "label": "Text Block Content",
                            "id": "text_block",
                            "default": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed pellentesque tortor ante, id maximus massa volutpat et. Aliquam at leo a purus condimentum tristique. Nulla feugiat enim quis neque suscipit, sed dictum quam tempor. Morbi purus metus, porta tincidunt justo eget, mollis volutpat justo. Suspendisse enim est, tristique vel nisl in, facilisis aliquam risus. Nunc placerat quam quam, eget blandit augue finibus sed. Donec in facilisis urna, eu egestas diam. Maecenas consequat a lacus et pharetra. Nullam sodales mi sed libero venenatis placerat. Proin quis pharetra metus. Suspendisse elementum at libero nec dignissim. In convallis imperdiet turpis eget hendrerit. Quisque sapien enim, vestibulum vitae ullamcorper et, rutrum faucibus nunc."
                        }
                    ]
                }
            ]
        }
    ],
    "template": "<h2>{{heading_text}}</h2>\n<img src=\"{{image.src}}\" width=\"{{width}}\" />\n<div>{{text_block}}</div>"
}

Create and Use the Widget Template

Having written the schema and markup, you are now ready to use the Widgets API to create a widget template. You will begin by writing the API request body, then you will use a REST client to create the template, then you will test your template in Page Builder.

1. Write a JSON object including a name, schema, and template using the schema and escaped markup as the schema and template respectively, and with a descriptive name.

Example:

{
	"name": "Static Image + Content",
	"schema": [
        {
            "type": "tab",
            "label": "Static Content",
            "sections": [
                {
                    "label": "Static Content",
                    "settings": [
                        {
                            "type": "input",
                            "id": "heading_text",
                            "label": "Heading Text",
                            "default": "Type a Heading"
                        },
                        {
                            "type": "imageManager",
                            "id": "image",
                            "label": "Image",
                            "default": {
                                "src": "https://placehold.it/250x250",
                                "type": "IMAGE_MANAGER"
                            }
                        },
                        {
                            "type": "range",
                            "label": "Image Width",
                            "id": "width",
                            "default": "250",
                            "typeMeta": {
                                "rangeValues": {
                                    "min": 100,
                                    "max": 1200,
                                    "step": 1,
                                    "unit": "px"
                                }
                            }
                        },
                        {
                            "type": "text",
                            "label": "Text Block Content",
                            "id": "text_block",
                            "default": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed pellentesque tortor ante, id maximus massa volutpat et. Aliquam at leo a purus condimentum tristique. Nulla feugiat enim quis neque suscipit, sed dictum quam tempor. Morbi purus metus, porta tincidunt justo eget, mollis volutpat justo. Suspendisse enim est, tristique vel nisl in, facilisis aliquam risus. Nunc placerat quam quam, eget blandit augue finibus sed. Donec in facilisis urna, eu egestas diam. Maecenas consequat a lacus et pharetra. Nullam sodales mi sed libero venenatis placerat. Proin quis pharetra metus. Suspendisse elementum at libero nec dignissim. In convallis imperdiet turpis eget hendrerit. Quisque sapien enim, vestibulum vitae ullamcorper et, rutrum faucibus nunc."
                        }
                    ]
                }
            ]
        }
    ],
    "template": "<h2>{{heading_text}}</h2>\n<img src=\"{{image.src}}\" width=\"{{width}}\" />\n<div>{{text_block}}</div>"
}

2. Use your REST client to send your object as a POST request body to the Create a Widget Template API.
3. After you send the request, your new widget should be available in Page Builder. Open Page Builder by navigating to Storefront > Customize in the BigCommerce. Look below the default list of basic widgets to find the Custom section:

Try dragging your custom widget onto the page. Assuming the schema is structured correctly, you should be able to modify the settings in the left sidebar. The end result should look something like this:

Section Challenge

For an extra challenge, try implementing new settings to control the typography and styling of the widget.

• Consider use cases like image alignment, changing the font in the text block or setting image border.
• Consider using other schema settings types like select or color:
• Query the Get All Widget Templates API to examine the basic widget templates for more ideas.