Widget UI Schema
Plan: Stencil Developer
Lesson 8 of 22 · 45 minWhen 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.
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.
- 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
- 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.
- 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:
| Setting | Description |
|---|---|
| type | The type of setting component to display. You can view the list of elements below to discover which are available to use. |
| label | The user-friendly message to inform the user how they can use this setting. |
| id | The variable name where the setting value will be available in the widget template. |
| default | The default value to use when rendering the widget for the first time. |
| typeMeta | Additional information needed based on the selected setting type. |
| conditional | An 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
- 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
{ "type": "boolean", "label": "Enable touch support", "id": "draggable", "default": true } Setting output: { "draggable": true }
Box Model
- 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
- 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 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
- 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
{ "type": "input", "label": "Alt text", "id": "altText", "default": "A cool grey shirt" } Setting output: { "altText": "A cool grey shirt" }
Number
- 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
- 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
- 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
- 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 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
{ "type": "select", "label": "Link decoration", "id": "linkDecoration", "default": "none", "typeMeta": { "selectOptions" : [ { "label": "None", "value": "none" }, { "label": "Underline", "value": "underline" } ] } } Setting output: { "linkDecoration": "none" }
Text
- 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
- 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
[ { "type": "tab", "label": "Content", "sections": [ { "label": "Product cards", "settings": [ { "type": "boolean", "label": "Show product name", "id": "showProductName", "default": true }, { "type": "boolean", "label": "Show product description", "id": "showProductDescription", "default": true }, { "type": "boolean", "label": "Show product ratings", "id": "showProductRatings", "default": true }, { "type": "boolean", "label": "Show product price", "id": "showProductPrice", "default": true }, { "type": "boolean", "label": "Show button", "id": "showButton", "default": true }, { "type": "select", "label": "Number of products per row", "id": "productsPerRow", "default": "3", "typeMeta": { "selectOptions" : [ { "label": "2", "value": "2" }, { "label": "3", "value": "3" }, { "label": "4", "value": "4" } ] } } ] }, { "label": "Button", "settings": [ { "type": "input", "label": "Button label", "id": "buttonLabel", "default": "Add to Cart" }, { "type": "select", "label": "Button action", "id": "buttonActionType", "default": "addToCart", "typeMeta": { "selectOptions" : [ { "label": "Add to Cart", "value": "addToCart" }, { "label": "Add to Wishlist", "value": "addToWishlist" }, { "label": "Go to Product Page", "value": "goToProduct" } ] } } ] } ] }, { "type": "tab", "label": "Design", "sections": [ { "label": "Product cards", "settings": [ { "type": "color", "label": "Background color", "id": "productCardBackgroundColor", "default": "rgba(255,255,255,1)" }, { "type": "color", "label": "Border color", "id": "productCardBorderColor", "default": "#D9DCE9" }, { "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" } } }, { "type": "boxModel", "label": "Padding", "id": "productCardPadding", "default": { "top": { "value": "0", "type": "px" }, "right": { "value": "0", "type": "px" }, "bottom": { "value": "16", "type": "px" }, "left": { "value": "0", "type": "px" } } }, { "type": "alignment", "label": "Content alignment", "id": "productCardContentAlignment", "default": { "horizontal": "center" }, "typeMeta": { "display": "horizontal" } } ] }, { "label": "Product image", "settings": [ { "type": "input", "label": "Image height (px)", "id": "productImageHeight", "default": "252" } ] }, { "label": "Product name", "settings": [ { "type": "select", "label": "Font family", "id": "productNameFontFamily", "default": "inherit", "typeMeta": { "selectOptions" : [ { "label": "Default", "value": "inherit" }, { "label": "Arial", "value": "Arial" }, { "label": "Times New Roman", "value": "Times New Roman" }, { "label": "Karla", "value": "Karla" }, { "label": "Roboto", "value": "Roboto" }, { "label": "Source Sans Pro", "value": "Source Sans Pro" }, { "label": "Montserrat", "value": "Montserrat" }, { "label": "Open Sans", "value": "Open Sans" }, { "label": "Volkhov", "value": "Volkhov" } ] } }, { "type": "select", "label": "Font weight", "id": "productNameFontWeight", "default": "400", "typeMeta": { "selectOptions" : [ { "label": "Thin", "value": "100" }, { "label": "Extra Light (Ultra Light)", "value": "200" }, { "label": "Light", "value": "300" }, { "label": "Normal", "value": "400" }, { "label": "Medium", "value": "500" }, { "label": "Semi Bold (Demi Bold)", "value": "600" }, { "label": "Bold", "value": "700" }, { "label": "Extra Bold (Ultra Bold)", "value": "800" }, { "label": "Black (Heavy)", "value": "900" } ] } }, { "type": "input", "label": "Font size (px)", "id": "productNameFontSize", "default": "22" }, { "type": "input", "label": "Line height (px)", "id": "productNameLineHeight", "default": "33" }, { "type" : "toggle", "id": "productNamePseudo", "default": "normal", "typeMeta": { "selectOptions": [ { "label": "Normal", "value": "normal" }, { "label": "Hover", "value": "hover" } ], "conditionalSettings": [ { "condition": "normal", "settings": [ { "type": "color", "label": "Text color", "id": "productNameTextColor", "default": "#000000" }, { "type": "select", "label": "Text decoration", "id": "productNameTextDecoration", "default": "none", "typeMeta": { "selectOptions" : [ { "label": "None", "value": "none" }, { "label": "Underline", "value": "underline" } ] } } ] }, { "condition": "hover", "settings": [ { "type": "color", "label": "Text color", "id": "productNameTextColorHover", "default": "#000000" }, { "type": "select", "label": "Text decoration", "id": "productNameTextDecorationHover", "default": "none", "typeMeta": { "selectOptions" : [ { "label": "None", "value": "none" }, { "label": "Underline", "value": "underline" } ] } } ] } ] } } ] }, { "label": "Product description", "settings": [ { "type": "select", "label": "Font family", "id": "productDescriptionFontFamily", "default": "inherit", "typeMeta": { "selectOptions" : [ { "label": "Default", "value": "inherit" }, { "label": "Arial", "value": "Arial" }, { "label": "Times New Roman", "value": "Times New Roman" }, { "label": "Karla", "value": "Karla" }, { "label": "Roboto", "value": "Roboto" }, { "label": "Source Sans Pro", "value": "Source Sans Pro" }, { "label": "Montserrat", "value": "Montserrat" }, { "label": "Open Sans", "value": "Open Sans" }, { "label": "Volkhov", "value": "Volkhov" } ] } }, { "type": "select", "label": "Font weight", "id": "productDescriptionFontWeight", "default": "400", "typeMeta": { "selectOptions" : [ { "label": "Thin", "value": "100" }, { "label": "Extra Light (Ultra Light)", "value": "200" }, { "label": "Light", "value": "300" }, { "label": "Normal", "value": "400" }, { "label": "Medium", "value": "500" }, { "label": "Semi Bold (Demi Bold)", "value": "600" }, { "label": "Bold", "value": "700" }, { "label": "Extra Bold (Ultra Bold)", "value": "800" }, { "label": "Black (Heavy)", "value": "900" } ] } }, { "type": "input", "label": "Font size (px)", "id": "productDescriptionFontSize", "default": "14" }, { "type": "input", "label": "Line height (px)", "id": "productDescriptionLineHeight", "default": "21" }, { "type": "color", "label": "Text color", "id": "productDescriptionTextColor", "default": "#000000" } ] }, { "label": "Product ratings", "settings": [ { "type": "color", "label": "Star ratings color (full)", "id": "productRatingStarColorFull", "default": "#80000B" }, { "type": "color", "label": "Star ratings color (empty)", "id": "productRatingStarColorEmpty", "default": "#D9DCE9" }, { "type": "color", "label": "Reviews text color", "id": "productRatingsTextColor", "default": "#8C93AD" } ] }, { "label": "Product price", "settings": [ { "type": "select", "label": "Font family", "id": "productPriceFontFamily", "default": "inherit", "typeMeta": { "selectOptions" : [ { "label": "Default", "value": "inherit" }, { "label": "Arial", "value": "Arial" }, { "label": "Times New Roman", "value": "Times New Roman" }, { "label": "Karla", "value": "Karla" }, { "label": "Roboto", "value": "Roboto" }, { "label": "Source Sans Pro", "value": "Source Sans Pro" }, { "label": "Montserrat", "value": "Montserrat" }, { "label": "Open Sans", "value": "Open Sans" }, { "label": "Volkhov", "value": "Volkhov" } ] } }, { "type": "select", "label": "Font weight", "id": "productPriceFontWeight", "default": "400", "typeMeta": { "selectOptions" : [ { "label": "Thin", "value": "100" }, { "label": "Extra Light (Ultra Light)", "value": "200" }, { "label": "Light", "value": "300" }, { "label": "Normal", "value": "400" }, { "label": "Medium", "value": "500" }, { "label": "Semi Bold (Demi Bold)", "value": "600" }, { "label": "Bold", "value": "700" }, { "label": "Extra Bold (Ultra Bold)", "value": "800" }, { "label": "Black (Heavy)", "value": "900" } ] } }, { "type": "input", "label": "Font size (px)", "id": "productPriceFontSize", "default": "14" }, { "type": "input", "label": "Line height (px)", "id": "productPriceLineHeight", "default": "21" }, { "type": "color", "label": "Text color", "id": "productPriceTextColor", "default": "#000000" } ] }, { "label": "Button", "settings": [ { "type": "range", "label": "Border radius", "id": "buttonBorderRadius", "default": 4, "typeMeta": { "rangeValues": { "min": 0, "max": 100, "step": 1, "unit": "px" } } }, { "type": "select", "label": "Font family", "id": "buttonFontFamily", "default": "inherit", "typeMeta": { "selectOptions" : [ { "label": "Default", "value": "inherit" }, { "label": "Arial", "value": "Arial" }, { "label": "Times New Roman", "value": "Times New Roman" }, { "label": "Karla", "value": "Karla" }, { "label": "Roboto", "value": "Roboto" }, { "label": "Source Sans Pro", "value": "Source Sans Pro" }, { "label": "Montserrat", "value": "Montserrat" }, { "label": "Open Sans", "value": "Open Sans" }, { "label": "Volkhov", "value": "Volkhov" } ] } }, { "type": "select", "label": "Font weight", "id": "buttonFontWeight", "default": "400", "typeMeta": { "selectOptions" : [ { "label": "Thin", "value": "100" }, { "label": "Extra Light (Ultra Light)", "value": "200" }, { "label": "Light", "value": "300" }, { "label": "Normal", "value": "400" }, { "label": "Medium", "value": "500" }, { "label": "Semi Bold (Demi Bold)", "value": "600" }, { "label": "Bold", "value": "700" }, { "label": "Extra Bold (Ultra Bold)", "value": "800" }, { "label": "Black (Heavy)", "value": "900" } ] } }, { "type": "input", "label": "Font size (px)", "id": "buttonFontSize", "default": "14" }, { "type" : "toggle", "id": "buttonPseudo", "default": "normal", "typeMeta": { "selectOptions": [ { "label": "Normal", "value": "normal" }, { "label": "Hover", "value": "hover" } ], "conditionalSettings": [ { "condition": "normal", "settings": [ { "type": "color", "label": "Text color", "id": "buttonTextColor", "default": "rgba(255,255,255,1)" }, { "type": "select", "label": "Text decoration", "id": "buttonTextDecoration", "default": "none", "typeMeta": { "selectOptions" : [ { "label": "None", "value": "none" }, { "label": "Underline", "value": "underline" } ] } }, { "type": "color", "label": "Button color", "id": "buttonColor", "default": "rgba(68,68,68,1)" }, { "type": "color", "label": "Border color", "id": "buttonBorderColor", "default": "rgba(102,102,102,1);" } ] }, { "condition": "hover", "settings": [ { "type": "color", "label": "Text color", "id": "buttonTextColorHover", "default": "rgba(255,255,255,1)" }, { "type": "select", "label": "Text decoration", "id": "buttonTextDecorationHover", "default": "none", "typeMeta": { "selectOptions" : [ { "label": "None", "value": "none" }, { "label": "Underline", "value": "underline" } ] } }, { "type": "color", "label": "Button color", "id": "buttonColorHover", "default": "rgba(102,102,102,1);" }, { "type": "color", "label": "Border color", "id": "buttonBorderColorHover", "default": "rgba(102,102,102,1);" } ] } ] } } ] }, { "label": "Arrows", "settings": [ { "type": "color", "label": "Arrow color", "id": "carouselArrowColor", "default": "#D9DCE9" }, { "type": "color", "label": "Arrow background color", "id": "carouselArrowBackgroundColor", "default": "rgba(255,255,255,0.0)" }, { "type": "color", "label": "Arrow border color", "id": "carouselArrowBorderColor", "default": "rgba(255,255,255,0.0)" } ] }, { "label": "Animation and effects", "settings": [ { "type": "boolean", "label": "Touch support", "id": "draggable", "default": true }, { "type": "select", "label": "Easing method", "id": "easingMethod", "default": "ease", "typeMeta": { "selectOptions" : [ { "label": "Ease", "value": "ease" }, { "label": "Linear", "value": "linear" }, { "label": "Ease-in", "value": "ease-in" }, { "label": "Ease-out", "value": "ease-out" }, { "label": "Ease-in-out", "value": "ease-in-out" } ] } }, { "type": "input", "label": "Animation duration (ms)", "id": "animationDuration", "default": "400" } ] } ] }, { "type": "array", "label": "Product List", "id": "products", "defaultCount": 3, "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" } }, { "type": "input", "label": "Description", "id": "productDescription", "default": "" }, { "type": "productImage", "label": "Product image", "id": "productImage", "typeMeta": { "reference": "productId" } }, { "type": "select", "label": "Image fit", "id": "productImageFit", "default": "fit", "typeMeta": { "selectOptions" : [ { "label": "Fill to box", "value": "fill" }, { "label": "Fit to box", "value": "fit" } ] } }, { "type": "alignment", "label": "Image alignment", "id": "productImageAlignment", "default": { "horizontal": "center", "vertical": "middle" }, "typeMeta": { "display": "both" } } ] } ] } ] } ]
