Lab - Create a Widget Template for Static Content
Lab - Create a Widget Template for Static Content
Lab - Create a Widget Template for Static Content
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
Prerequisites
This lab primarily focuses on creating widget templates, but before creating the widget it’s helpful to explore the relationships between:
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.
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:
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
Use a text editor of your choice to write JSON for the following steps. These steps will walk you through creating the schema array in the Create a Widget Template request. To create the configurable fields in the Page Builder sidebar, the schema must include exactly one tab at the root level to contain all visible sections. The sections within the tab will correspond to the controls for heading text, image upload, image width, and text block content.
For more information on tabs and sections, see the BigCommerce Dev Docs
At this point, your schema should contain the same settings the schema array in this example.
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:
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”:
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.
You should now have 3 lines of HTML:
At this point, you should have a line of code that matches the template in the example:
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.
Example:
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:
For an extra challenge, try implementing new settings to control the typography and styling of the widget.