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.
Within the schema property of the Create a Widget Template endpoint, settings are grouped into tabs and sections.
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.
[{ "type": "tab", "label": "Content", "sections": [...] }, { "type": "tab", "label": "Design", "sections": [...] }]
[{ "type": "tab", "label": "Content", "sections": { "label": "Product ratings", "settings": [...] } }]
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.
{ "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" } } ] } ] } ] }
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" } ] }
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.
{ "type": "alignment", "label": "Content alignment", "id": "contentAlignment", "default": { "horizontal": "center", "vertical": "middle" }, "typeMeta": { "display": "both" } } Setting output: { "contentAlignment": { "horizontal": "center", "vertical": "middle" } }
{ "type": "boolean", "label": "Enable touch support", "id": "draggable", "default": true } Setting output: { "draggable": true }
{ "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" } } }
{ "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>" }
{ "type": "color", "label": "Star ratings color (full)", "id": "productRatingStarColorFull", "default": "#80000B" } Setting output: { "productRatingStarColorFull": "#80000B" }
{ "type": "imageManager", "id": "imageUrl", "default": "https://images.unsplash.com/photo-1548768041" } Setting output: { "imageUrl": "https://images.unsplash.com/photo-1548768041" }
{ "type": "input", "label": "Alt text", "id": "altText", "default": "A cool grey shirt" } Setting output: { "altText": "A cool grey shirt" }
{ "type": "number", "label": "Font size", "id": "fontSize", "default": { "value": 32, "type": "px" }, "typeMeta": { "parseType": "integer" } } Setting output: { "fontSize": { "value": 32, "type": "px" } }
{ "type": "productId", "label": "Product", "id": "productId", "typeMeta": { "placeholder": "Search by name or SKU" } } Setting output: { "productId":"80" }
{ "type": "productImage", "label": "Product image", "id": "productImage", "typeMeta": { "reference": "productId" } } Setting output: { "productImage": "https://store-url.com/products/80/images/272.png" }
{ "type": "range", "label": "Border radius", "id": "buttonBorderRadius", "default": 4, "typeMeta": { "rangeValues": { "min": 0, "max": 100, "step": 1, "unit": "px" } } } Setting output: { "buttonBorderRadius": 4 }
{ "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" } } }
{ "type": "select", "label": "Link decoration", "id": "linkDecoration", "default": "none", "typeMeta": { "selectOptions" : [ { "label": "None", "value": "none" }, { "label": "Underline", "value": "underline" } ] } } Setting output: { "linkDecoration": "none" }
{ "type": "text", "label": "Body text", "id": "bodyText", "default": "This is some text." } Setting output: { "bodyText": "This is some text." }
{ "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
[ { "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" } } ] } ] } ] } ]