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 the labelResourceId 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 the labelResourceId, and an optional block of descriptive help text, defined by the helpTextResourceId, 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 the maxLength property. For example:
```
{
            "id": "collectionItem",   "type": "collectionType",
            "name": "collectionPickerValue",
            "helpTextResourceId": "collectionPickerValueHelpText",
            "labelResourceId": "collectionPickerValueLabel",
            "maxLength": 5 
}
```

multiSelectOptionType: Produces a list of preset values, as does optionType; 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 the displayAsCheckboxes 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>