Widget UI Schema
This document outlines the different schema settings you can use in your custom widget template. For a tutorial on creating widget templates, see Widgets Tutorial.
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.
[{
"type": "tab",
"label": "Content",
"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": "Text",
"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.
{
"type": "array",
"label": "Carousel",
"id": "slides",
"defaultCount": 2,
"entryLabel": "Slide",
"thumbnail": {
"type": "image",
"valueKey": "imageUrl.src"
},
"schema": [
{
"type": "tab",
"label": "Content",
"sections": [
...
{
"type": "imageManager",
"id": "imageUrl",
"default": {
"src": "https://example.com/example.png",
"type": "IMAGE_MANAGER"
}
},
...
]
}
]
}
- 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.
Hidden settings
You can use hidden settings to set up controls which 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 fields
The following table contains fields common between schema settings. For additional details, see the Create a Widget Template endpoint.
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. |
For examples of different schema settings you can use in your custom widget template, see Widget UI Input Types.