Skip to content
Tutorials Center
My learning

Topics

Lesson 15 of 28 ยท Widgets and Page Builder

Widgets, Regions and Page Builder

Learn how merchants edit pages without code: widget templates and schemas, theme regions, Page Builder, placements, and the Script Manager for tags and footers.

A theme gives a store its structure, but merchants want to change banners, text blocks and promotions without calling a developer. BigCommerce solves this with widgets and regions. A developer defines a widget (a reusable block with settings) and marks regions in the theme where widgets may go. The merchant then drags widgets into regions in Page Builder, the visual editor, and fills in the settings. A related tool, the Script Manager, lets a store add tracking tags and other scripts without editing theme files.

The real tools run inside the BigCommerce control panel and its APIs, so the platform code in this lesson is read-only. The runnable parts are JavaScript stand-ins that model the ideas: a widget renderer driven by a schema, a region that places widgets in order, and a script filter. They are our own code, not BigCommerce's, and the lesson says where they simplify. If themes are new to you, read Handlebars Templates, Helpers and Page Context and Theme Settings, SCSS and JavaScript first.

The pieces and how they connect

There are four parts, and it helps to keep them apart:

  1. A widget template is the blueprint: a name, a schema describing the settings a merchant can edit, and a Handlebars template that renders the HTML.
  2. A widget is an instance of a template with specific values for the settings, such as "Summer sale banner" with its heading and color.
  3. A region is a named spot in a theme template where widgets can be placed.
  4. A placement puts one widget into one region of one template file, at a position in the order.
flowchart LR
    WT["Widget template<br/>(schema + Handlebars)"] --> W["Widget<br/>(values for the settings)"]
    W --> P["Placement<br/>(region + template file + sort order)"]
    R["Region in a theme template"] --> P
    P --> H["Rendered HTML on the page"]

A widget template is instantiated as a widget, and a placement connects it to a region.

Because widgets are separate from the theme, they can be reused on several pages, and a merchant can edit them without touching code. Changing the blueprint (the template) changes every widget made from it.

Regions in the theme

A theme marks a region with the region helper, which you met in the Handlebars lesson (read-only):

HTML
{{{region name="home_below_menu"}}}
<main>
  ...
</main>
{{{region name="home_below_content"}}}

The region name is the identifier; the page template it appears in matters too, because a placement is tied to a region name and a template file together. Choose names that describe the location (home_below_menu, product_below_content) and keep them stable, because renaming a region orphans the widgets that were placed in it. Cornerstone and other starter themes ship with a set of regions on the main pages; you add more where your design needs a merchant-editable area.

Regions are output with triple curly braces because the helper returns HTML. A region with no widgets renders nothing, so adding a region never changes a page until somebody uses it.

Widget templates and schemas

You create a widget template with the Widget Builder, either in the control panel's Page Builder tools or through the Content API (read-only sketch; the exact property names and allowed setting types are in the current Content API reference):

JSON
{
  "name": "Promo banner",
  "template": "<div class=\"promo\" style=\"background:{{backgroundColor}}\"><h2>{{heading}}</h2>{{#if linkUrl}}<a href=\"{{linkUrl}}\">{{linkText}}</a>{{/if}}</div>",
  "schema": [
    {
      "type": "tab",
      "label": "Content",
      "sections": [
        {
          "label": "Text",
          "settings": [
            { "type": "input", "label": "Heading", "id": "heading", "default": "Big sale" },
            { "type": "input", "label": "Link text", "id": "linkText", "default": "Shop now" },
            { "type": "input", "label": "Link URL", "id": "linkUrl" }
          ]
        },
        {
          "label": "Style",
          "settings": [
            { "type": "color", "label": "Background", "id": "backgroundColor", "default": "#fff4e5" }
          ]
        }
      ]
    }
  ]
}

The schema is a list of tabs, each with sections, each with settings. Each setting has a type (such as a text input, color, boolean, select, alignment, image picker or product picker), a label shown in the editor, an id and an optional default. The id is the name your template reads: {{heading}} prints the value of the setting with the id heading. This is the same pattern as theme settings in schema.json, but with the values stored per widget instead of per theme.

Design widgets as small, single-purpose blocks. A "promo banner" with six settings is easy for a merchant to use; a "universal block" with forty settings is not. Give every setting a sensible default, because a merchant who drops a widget in and sees nothing will assume it is broken. Escape rules from the Handlebars lesson apply: use double curlies for text, and be careful before using raw output for anything a merchant types.

A widget renderer you can run

The stand-in below does what the platform does for you: validates the merchant's values against the schema, fills in defaults, and renders the template with the final values. The template engine here is a toy that supports {{id}} (escaped) and {{#if id}}...{{/if}}.

JS Render a widget from a schema

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The first case renders defaults and no link, because linkUrl is empty and the if hides it. The second shows the escaped heading (Winter &lt;sale&gt;) and the link. The third reports the invalid color and falls back to the default. In the real editor, the color picker prevents that mistake before it is saved.

Placements and Page Builder

A widget does nothing until it is placed. A placement says: put widget X in region home_below_menu of the template file pages/home, at sort position 1, and make it active. Merchants usually do this by dragging in Page Builder, which writes placements for them. Developers can create them with the Content API, which is how apps and import scripts add content (read-only sketch):

JSON
{
  "widget_uuid": "<uuid of the widget>",
  "region": "home_below_menu",
  "template_file": "pages/home",
  "sort_order": 1,
  "status": "active"
}

Placements are what makes the same widget appear on several pages, or in several regions: one placement per spot. Setting status to inactive hides it without deleting it, which is good for scheduled campaigns.

Page Builder is the editor around all this. A merchant opens it from the theme customizer, sees the page with its regions highlighted, edits widget settings in a side panel and publishes when ready. Your job as a developer is to make that experience good: clear region names, widgets with helpful labels and defaults, and a theme that still looks right with every region empty or full.

A region stand-in

The next stand-in models a region. It keeps a list of placements, picks those for one region and template file, drops the inactive ones, sorts by sort_order, and renders the widgets in sequence. Widgets here are simple functions, to keep the focus on the placement logic.

JS Render a region from placements

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The home region shows the banner first and the products second although they were listed in the opposite order, because of sort_order. The inactive notice is skipped, the same widget appears on the product page through a separate placement, and a region with no placements renders an empty string.

Script Manager: tags, pixels and footers

Not everything should be a widget. Analytics tags, chat widgets, consent tools and tracking pixels are scripts, and the Script Manager (in the control panel, and through the Scripts API) is the place for them. A script has a location (head or footer), a set of pages where it loads (all pages, only the storefront, checkout, or the order confirmation page), a load method (default, async or defer) and a consent category (essential, functional, analytics or targeting), so that the store's cookie banner can decide whether it may run. Read-only sketch of creating one with the API, which needs the right Content scope on your token (see API Accounts, Tokens and Scopes):

Terminal
curl -X POST "$BC_API_BASE/v3/content/scripts" \
  -H "X-Auth-Token: $BC_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Analytics tag",
    "description": "Page view tracking",
    "src": "https://cdn.example.com/analytics.js",
    "auto_uninstall": true,
    "load_method": "async",
    "location": "footer",
    "visibility": "all_pages",
    "kind": "src",
    "consent_category": "analytics"
  }'

An app that installs a script should set auto_uninstall so the script disappears when the app is removed; leftover scripts from uninstalled apps are a common cause of slow, broken stores. Keep the marketing and privacy rules in mind: load only what you need, respect consent, and read Analytics and Tracking and Privacy and Compliance before adding trackers.

The stand-in below models which scripts would load for a given page and consent state. It shows why the filter has three parts: page visibility, location, and consent.

JS Which scripts load on this page?

Press Run (or Ctrl + Enter) to see the console output here.

No output.

With no consent, only the essential font script loads. With analytics and functional consent, the analytics tag and chat widget join it, but the ad pixel stays out. On the confirmation page, the order-tracking script appears and the storefront-only scripts do not.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What connects a widget to a specific place on a page?

    A placement ties one widget to a region of one template file and gives its position in the order.
  2. 2. Which item defines the settings a merchant can edit in a widget?

    The schema lists tabs, sections and settings with ids, labels and defaults. The template reads the values through the setting ids.
  3. 3. Why give every widget setting a sensible default?

    Good defaults make a widget usable immediately and let merchants refine it.
  4. 4. Why set auto_uninstall on a script that an app installs?

    Without it, scripts can stay behind after an app is removed, slowing the store and sometimes breaking pages.

Summary

  • A widget template (schema plus Handlebars) is instantiated as widgets, and placements put widgets into regions.
  • Regions are marked in theme templates with the region helper; keep their names stable.
  • Page Builder is the visual editor merchants use to place widgets and edit their settings.
  • Widget schemas are tabs, sections and settings with ids, labels and defaults; small, single-purpose widgets are best.
  • The Script Manager handles tags, pixels and footers with location, page visibility, load method and consent category.
  • The renderer, region and script filter in this lesson are stand-ins that model the logic, not BigCommerce's own code.

Next: Carts and the Checkout API