CoursesWidgets - REST APIModule 4: Schema

Widget UI Schema

Plan: Stencil Developer

 Lesson 8 of 22 · 45 min

When building custom widgets, the schema property allows the widget template developer to build custom user interfaces within the BigCommerce page builder platform. BigCommerce provides all the setting logic and design, the widget author just needs to tell us about the various settings that make up the widget. These settings make building custom widgets fast and easy! This is the exact mechanism we use for all the platform-provided widgets as well.

Example of a widget template settings menu, you can see many of the types of setting controls BigCommerce provides. View schema code.

Tabs and Sections

Within the schema property of the Create a Widget Template endpoint, settings are grouped into tabs and sections.

Tabs

Tabs are a part of the Page Builder schema structure. The schema requires using a single root-level tab to contain all visible sections.

Sections render in the same order they are listed within a tab.

Tabs in widget schema

  • When there is only a single tab, the tab interface will not be shown
  • Tabs will display in the order they are provided.
  • Tabs contain a list of sections which are rendered in the order in which they are provided.
[{
  "type": "tab",
  "label": "Content",
  "sections": [...]
},
{
  "type": "tab",
  "label": "Design",
  "sections": [...]
}]

Sections

Product ratings widget

  • Sections are groups of related settings.
  • Each section will have a title that the user can collapse.
  • Section labels are optional but are not collapsible without a label.
  • Settings render in the same order they are listed within a section.
[{
  "type": "tab",
  "label": "Content",
  "sections": {
    "label": "Product ratings",
    "settings": [...]
  }
}]

Array Type

Arrays allow for building collections of elements within the widget. Array elements live at the top level of the schema. Each element in the array can contain an entire schema.

Elements in the list have settings defined by the array’s schema, which you can build using tabs, sections, and settings.

Array schema

  • Each element in the list can have tabs and sections included.
  • The defaultCount attribute is the number of elements that are displayed in the list by default.
  • Use the thumbnail attribute to display an image stored at the specified attribute name.
  • Use the entryLabel attribute to set a name for each element in the list.
{
  "type": "array",
  "label": "Product list",
  "id": "products",
  "defaultCount": 2,
  "entryLabel": "Product",
  "thumbnail": "productImage",
  "schema": [
    {
      "type": "tab",
      "label": "Product",
      "sections": [
        {
          "label": "Display",
          "settings": [
            {
              "type": "productId",
              "label": "Product",
              "id": "productId",
              "typeMeta": {
                 "placeholder": "Search by name or SKU"
              }
            }
          ]
        }
      ]
    }
  ]
}

Hidden Settings

You can use hidden settings to set up controls that have no user interface drawn in Page Builder. Hidden settings live at the schema’s top level because they are not grouped into any other tabs or arrays. You can use them in advanced widgets with complex interactions in the preview pane, such as inline editing.

{
  "type": "hidden",
  "settings": [
    {
      "id": "title",
      "default": "Sample title text"
    },
    {
      "id": "subtitle",
      "default": "Description text goes here"
    }
  ]
}

Schema Settings

Common fields between schema settings:

SettingDescription
typeThe type of setting component to display. You can view the list of elements below to discover which are available to use.
labelThe user-friendly message to inform the user how they can use this setting.
idThe variable name where the setting value will be available in the widget template.
defaultThe default value to use when rendering the widget for the first time.
typeMetaAdditional information needed based on the selected setting type.
conditionalAn optional property that can be added to each setting to control whether it should be displayed to the user while editing in Page Builder. This does not clear the value in the setting, just controls the display of the setting.

Below are examples of the different schema settings you can use in your custom widget template.

Alignment

Alignment setting

  • It is possible to display “horizontal”, “vertical”, or “both” alignment controls depending on use case
  • Possible values for horizontal are: “left”, “right”, “center”
  • Possible values for vertical are: “top”, “bottom”, “middle”
{
  "type": "alignment",
  "label": "Content alignment",
  "id": "contentAlignment",
  "default": {
    "horizontal": "center",
    "vertical": "middle"
  },
  "typeMeta": {
    "display": "both"
  }
}
Setting output: {
  "contentAlignment": {
    "horizontal": "center",
    "vertical": "middle"
  }
}

Boolean

Boolean setting

{
  "type": "boolean",
  "label": "Enable touch support",
  "id": "draggable",
  "default": true
}
Setting output:
{
  "draggable": true
}

Box Model

Box model setting

  • Note that currently, values are in string format. this may change to number in the future. Stay tuned for updates.
  • Clicking the lock will make sure all dimensions match the first value.
{
  "type": "boxModel",
  "label": "Margin",
  "id": "productCardMargin",
  "default": {
    "top": {
      "value": "0",
      "type": "px"
    },
    "right": {
      "value": "10.5",
      "type": "px"
    },
    "bottom": {
      "value": "0",
      "type": "px"
    },
    "left": {
      "value": "10.5",
      "type": "px"
    }
  }
}
Setting output:
{
  "productCardMargin": {
    "top": {
      "value": "0",
      "type": "px"
    },
    "right": {
      "value": "10.5",
      "type": "px"
    },
    "bottom": {
      "value": "0",
      "type": "px"
    },
    "left": {
      "value": "10.5",
      "type": "px"
    }
  }
}

Code

Code setting

  • In the future, we may add more options for the language (syntax highlighting). Currently only “HTML” is supported.
{
  "id": "htmlCode",
  "label": "HTML Code",
  "default": "<div>html code can go here</div>",
  "type": "code",
  "typeMeta": {
    "language": "html",
    "placeholder": "Insert HTML code here"
  }
}
Setting output:
{
  "html": "<div>html code can go here</div>"
}

Color

Color picker setting

  • Color picker supports RGBA
  • Transparent can be selected, in which case the returned value is ‘transparent’.
{
  "type": "color",
  "label": "Star ratings color (full)",
  "id": "productRatingStarColorFull",
  "default": "#80000B"
}
Setting output:
{
  "productRatingStarColorFull": "#80000B"
}

Image Manager

Image Manager setting

  • Uploaded images go to the stores Image Manager
  • “My Images” allows the user to select from previously uploaded images
{
  "type": "imageManager",
  "id": "imageUrl",
  "default": "https://images.unsplash.com/photo-1548768041"
}
Setting output:
{
  "imageUrl": "https://images.unsplash.com/photo-1548768041"
}

Input

Input setting

{
  "type": "input",
  "label": "Alt text",
  "id": "altText",
  "default": "A cool grey shirt"
}
Setting output:
{
  "altText": "A cool grey shirt"
}

Number

Number setting

  • Response value will be a number, including information about the type (px, rem, etc)
  • Two parse types are supported: “integer” and “float”
{
  "type": "number",
  "label": "Font size",
  "id": "fontSize",
  "default": {
    "value": 32,
    "type": "px"
  },
  "typeMeta": {
    "parseType": "integer"
  }
}
Setting output:
{
  "fontSize": {
    "value": 32,
    "type": "px"
  }
}

Product ID

Product ID setting

  • Note that currently, id values are in string format. This may change to number in the future. Stay tuned for updates.
{
  "type": "productId",
  "label": "Product",
  "id": "productId",
  "typeMeta": {
    "placeholder": "Search by name or SKU"
  }
}
Setting output:
{
  "productId":"80"
}

Product Image

Product Image setting

  • Looks up product images based on the reference attribute
  • Works nicely with productId setting type
{
  "type": "productImage",
  "label": "Product image",
  "id": "productImage",
  "typeMeta": {
    "reference": "productId"
  }
}
Setting output:
{
  "productImage": "https://store-url.com/products/80/images/272.png"
}

Range

Range setting

  • The units are not currently returned. Expect some updates to return unit / value similar to number type. Stay tuned for updates.
{
  "type": "range",
  "label": "Border radius",
  "id": "buttonBorderRadius",
  "default": 4,
  "typeMeta": {
    "rangeValues": {
      "min": 0,
      "max": 100,
      "step": 1,
      "unit": "px"
    }
  }
}
Setting output:
{
  "buttonBorderRadius": 4
}

Regex Input

Regex setting

  • Regex setting can capture and provide conditional state to other schema settings.
  • In the example, we only want to show the autoplay video setting if the user has a URL which includes “youtube” or “youtu”
{
  "type": "regexInput",
  "label": "Video URL (YouTube or Vimeo)",
  "id": "videoUrl",
  "default": "",
  "typeMeta": {
    "placeholder": "https://",
    "regExPatterns": [
      {
        "pattern": "(vimeo|youtube|youtu)",
        "matchIndex": 0,
        "configKey": "type"
      }
    ]
  }
}
[...]
{
  "type": "boolean",
  "label": "Autoplay video",
  "id": "autoplay",
  "default": false,
  "conditional": {
    "key": "videoUrl.parts.type",
    "operator": "IN",
    "value": [
      "youtube",
      "youtu"
    ]
  }
}
Setting output:
{
  "videoUrl": {
    "value": "https://www.youtube.com/watch?v=-5EQIiabJvk",
    "parts": {
      "type":"youtube"
    }
  }
}

Select

Select setting

{
  "type": "select",
  "label": "Link decoration",
  "id": "linkDecoration",
  "default": "none",
  "typeMeta": {
    "selectOptions" : [
      {
        "label": "None",
        "value": "none"
      },
      {
        "label": "Underline",
        "value": "underline"
      }
    ]
  }
}
Setting output:
{
  "linkDecoration": "none"
}

Text

Text setting

  • New line characters are not supported. This is similar to “input” type, but displays more of the text and wraps lines.
{
  "type": "text",
  "label": "Body text",
  "id": "bodyText",
  "default": "This is some text."
}
Setting output:
{
  "bodyText": "This is some text."
}

Toggle

Toggle setting

  • This should be used purely to conditionally render settings based on the users selection.
  • You can put other schema settings in each “condition” (color in this example)
{
  "type" : "toggle",
  "id": "buttonToggle",
  "default": "normal",
  "typeMeta": {
    "selectOptions": [
      {
        "label": "Normal",
        "value": "normal"
      },
      {
        "label": "Hover",
        "value": "hover"
      }
    ],
    "conditionalSettings": [
      {
        "condition": "normal",
        "settings": [
          {
            "type": "color",
            "label": "Border color",
            "id": "borderColor",
            "default": "#ff0000"
          }
        ]
      },
      {
        "condition": "hover",
        "settings": [
          {
            "type": "color",
            "label": "Border color",
            "id": "borderColorHover",
            "default": "#00ff00"
          }
        ]
      }
    ]
  }
}
Setting output: N/A

Completed Example