Add customizable widget settings
You can add settings to a widget that provide a finer level control over the widget’s behavior when it is added to a layout.
For example, the Related Products widget has settings that allow the page designer to specify the number of related products to show and whether to display the name or price for related products. Any customizable settings that have been configured for a widget are available via the widget’s Settings tab.
To view a widget’s Settings tab, perform the following steps:
- From the Design menu, select the Layout tab.
- From the Layout tab menu, select the layout that contains the
widget whose settings you want to view by clicking the grid view.
The layout shows all of the widgets used in the layout.
- Click on the widget’s setting icon to view the widget information. Depending on the widget you select, you may see different tabs available, such as Layout, Settings and About.
- When you have finished making your changes, click Save.
Any configurable widget settings you create are added to the widget’s view model and can be referenced from the widget’s HTML template using a data-bind
attribute. Examples for creating the data bind are provided later in this section.
Define a widget’s configurable settings
Widget settings are defined using a JSON-based schema. To add configurable settings to your widget, add the following files to your directory structure:
<extension-name> : the root folder of your extension
ext.json
widget/
<widget-type>/
widget.json
config/
config.json
locales/
en_US.json
fr_FR.json
The resource files for configurable widget settings are stored in locale
files within the /<widget-type>/config/locales
directory
and are not read from the widget’s localization resources. However, the structure of
these locale files is identical to those for widget localization resources; please
refer to Localize a widget for examples.
Note that defining the locales in the format language_country
(en_US
) may cause an error indicating that the locale file cannot be found. The locale folder should be named using the language only, and if country-specific strings are preferred, you can optionally include the locale_country
folder.
The structure of a config.json
file looks similar to the
following:
{
"widgetDescriptorName": "QuoteWidget",
"properties": [
{
"id": "quoteWidgetTitle",
"type": "sectionTitleType",
"helpTextResourceId": "quoteWidgetTitle1HelpText",
"labelResourceId": "quoteWidgetTitle1Label"
},
{
"id": "quoteText",
"type": "stringType",
"helpTextResourceId": "quoteTextHelpText",
"labelResourceId": "quoteTextLabel",
"defaultValue": "",
"required": true,
"maxLength": 50,
"minLength": 3,
"pattern": "regex"
},
{
"id": "quoteSource",
"type": "stringType",
"helpTextResourceId": "quoteSourceHelpText",
"labelResourceId": "quoteSourceLabel",
"defaultValue": ""
},
{
"id": "quoteStyle",
"type": "booleanType",
"helpTextResourceId": "quoteStyleHelpText",
"labelResourceId": "quoteStyleLabel",
"defaultValue": true
},
{
"id": "quoteSize",
"type": "optionType",
"helpTextResourceId": "quoteSizeHelpText",
"labelResourceId": "quoteSizeLabel",
"defaultValue": "medium",
"options": [
{
"id": "quoteSizeSmall",
"value": "small",
"labelResourceId": "quoteSizeSmallLabel"
}, {
"id": "quoteSizeMedium",
"value": "medium",
"labelResourceId": "quoteSizeMediumLabel"
},
{
"id": "quoteSizeLarge",
"value": "large",
"labelResourceId": "quoteSizeLargeLabel"
}
]
}
]
}
The widgetDescriptorName
property names the widget for which these settings are defined and it must match the name
property in the widget’s widget.json
file. The properties array defines the configurable settings that should be added to the widget’s Settings tab. For each property, the following standard keys are supported:
id
: A unique ID for the property. You use this ID in the widget’s HTML template to create a data-bind to the property.name
: A display name for the property that appears on the Settings tab. Note that while this property is still available for backwards compatibility, it is preferable to use thelabelResourceId
property, described below, to set the label for a property.type
: The data type of the property. Refer below for supported data types.helpTextResourceId
: The name of the key in the resource files whose value provides help text for the property.labelResourceId
: The name of the key in the resource files whose value provides a label for the property on the Settings tab.defaultValue
: The property’s default value, which must be a valid value for the property’s data type. See Use supported data types for configuration for more information on data types.required
: A Boolean flag that determine if the property requires a value.
Use supported data types for configuration
There are a number of data types that are supported for widget settings. To specify the data type for a setting, you set the type
key to one of the following values:
stringType
: Produces a text entry field that allows the page designer to specify a free form text value.optionType
: Produces a drop-down list of preset values. The values are specified using an options array, shown in the example above.booleanType
: Produces a checkbox that allows the property to be enabled or disabled.mediaType
: Produces a menu that allows you to select a media item (e.g. Image) from your library, or by uploading a new file.sectionTitleType
: Produces a read-only Section Title, defined by thelabelResourceId
, and an optional block of descriptive help text, defined by thehelpTextResourceId
, to allow you to group widget settings together. For example:{ "id": "quoteWidgetTitle", "type": "sectionTitleType", "helpTextResourceId": "quoteWidgetTitle1HelpText", "labelResourceId": "quoteWidgetTitle1Label" },
collectionType
: Produces a picker that allows you to select from the collections defined in your catalog. You define the maximum number of collections that can be chosen using themaxLength
property. For example:{ "id": "collectionItem", "type": "collectionType", "name": "collectionPickerValue", "helpTextResourceId": "collectionPickerValueHelpText", "labelResourceId": "collectionPickerValueLabel", "maxLength": 5 }
multiSelectOptionType
: Produces a list of preset values, as doesoptionType
; however, you can select multiple values from this list. By default, the control created for this data type is a drop-down list; however, you can add thedisplayAsCheckboxes
property to the setting definition and set it to true to display a set of checkboxes instead. For example:{ "id": "paymentMethodTypes", "type": "multiSelectOptionType", "name": "paymentMethodTypes", "required": true, "helpTextResourceId": "paymentMethodsHelpText", "labelResourceId": "paymentMethodsLabel", "defaultValue": "card", "displayAsCheckboxes": true, "options": [ { "id": "card", "value": "card", "labelResourceId": "cardLabel" } ] }
Depending on the data type it uses, a property will also support a number of data type-specific keys. For the stringType data type, you can add the following keys:
minLength
: Minimum length of the string value.maxLength
: Maximum length of the string value.pattern
: A Java regular expression pattern to use for validating the string value. The pattern key can also be used to handle number expressions. For example, the configuration for a property that accepts a number in the range of 1 to 100 would look similar to the following:{ "id": "numberField", "type": "stringType", "name": "numberField", "helpTextResourceId": "numberHelpText", "labelResourceId": "numberLabel", "pattern": "^[1-9][0-9]?$|^100$" }
For the optionType
and multiSelectOptionType
data
types, you can add an options key that contains a list of objects that describe the
entries in the drop-down list. Each option has the following keys:
id
: Unique ID for the option.value
: The value of the option.labelResourceId
: The resource key used to display the option in the drop-down list.
As previously mentioned, the configurable settings you create are added to the widget’s view model and can be referenced from templates using a data-bind
attribute. For example:
<div class="quoteContainer" data-bind="style : {fontSize : quoteSize}">
<!-- ko ifnot : quoteText() == '' -->
<blockquote data-bind="css : {quoted : quoteStyle}">
<p data-bind="text: quoteText"></p>
<!-- ko ifnot : quoteSource() == '' -->
<footer data-bind="text : quoteSource"></footer>
<!-- /ko -->
</blockquote>
<!-- /ko --> </div>