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.
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 thelabelResourceIdproperty, described below, to set the label for a property.type: The data type of the property. Refer to Use supported data types for configuration 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 below for more information on data types.required: A Boolean flag that determine if the property requires a value.
