Define site settings

When you create widgets, you want to define the settings that it follows to display your site.

Site settings are defined using a JSON-based schema. To add site settings to your storefront, add the following files to your directory structure:

<extension-name> : extension root directory
     ext.json
     config/
         <settingsID>/ : site settings root directory
             config.json
             locales/
                en_US.json
                fr_FR.json

The resource bundles for site settings are stored in locale files under the /config/locales directory and look similar to the following:

{
  "resources" : {
    "enabledHelpText": "Enable the cart message.",
    "enabledLabel": "Cart Message",
    "couponHelpText": "Define the coupon name.",
    "couponLabel": "Coupon",
    "minSpendHelpText": "Define the minimum spend amount for the coupon.",
    "minSpendLabel": "Minimum Spend",
    "sizeHelpText": "The size of the banner.",
    "sizeLabel": "Banner Size",
    "sizeSmallLabel": "Small",
    "sizeMediumLabel": "Medium",
    "sizeLargeLabel": "Large",
    "passwordHelpText": "Set the value for API key.",
    "passwordLabel": "API Key",
    "title": "Sample Site Settings",
    "description":"Examples of site settings."
  }
 }

The structure of these files is identical to those for widget localization resources. Refer to Localize a widget for examples.

The structure of a config.json file looks similar to the following:

{
  "widgetDescriptorName": "multisiteconfigdemo",
  "titleResourceId": "title",
  "descriptionResourceId": "description",
  "properties": [
    {
      "id": "enabled",
      "type": "booleanType",
      "name": "enabled",
      "helpTextResourceId": "enabledHelpText",
      "labelResourceId": "enabledLabel",
      "defaultValue": true
    },
    {
      "id": "coupon",
      "type": "stringType",
      "name": "coupon",
      "helpTextResourceId": "couponHelpText",
      "labelResourceId": "couponLabel",
      "defaultValue": "SHIP100",
      "minLength": 6,
      "maxLength": 10,
      "required": true
    },
    {
      "id": "minSpend",
      "type": "stringType",
      "name": "minSpend",
      "helpTextResourceId": "minSpendHelpText",
      "labelResourceId": "minSpendLabel",
      "defaultValue": "100",
      "required": true
    },
    {
      "id": "password",
      "type": "passwordType",
      "name": "password",
      "helpTextResourceId": "passwordHelpText",
      "labelResourceId": "passwordLabel",
      "required": true
    },
    {
      "id": "bannerSize",
      "type": "optionType",
      "name": "bannerSize",
      "required": true,
      "helpTextResourceId": "sizeHelpText",
      "labelResourceId": "sizeLabel",
      "defaultValue": "s",
      "options": [
         {
           "id": "sizeSmall",
           "value": "s",
           "labelResourceId": "sizeSmallLabel"
         },
         {
           "id": "sizeMedium",
           "value": "m",
           "labelResourceId": "sizeMediumLabel"
         },
         {
           "id": "sizeLarge",
           "value": "l",
           "labelResourceId": "sizeLargeLabel"         }
       ] 
     }
   ]
 }

The titleResourceId property specifies a key in the resource bundles that is used to retrieve the title for the panel in the administration interface; for example, “Sample Site Settings” in the illustration above. The descriptionResourceId property specifies a key for the descriptive text that appears below the title. In the illustration, this is “Examples of site settings.”

The remainder of the config.json file consists of a properties array that defines individual site settings and their key/value pairs. Site settings use the same standard keys as configurable widget settings, namely id, name, type, helpTextResourceId, labelResourceId, defaultValue, and required. Site settings can also use the same data types that are available to configurable widget settings, for example, stringType, multiSelectOptionType, and so on. Both the standard keys and the data types are described in full detail in Define a widget's configurable settings.

Configure settings per site

Site settings can be configured on a site-by-site basis. If your Commerce instance is running multiple sites, the values a merchandiser specifies in a settings panel apply only to the currently selected site. The merchandiser can then select another site and supply different values for that site.

In some cases, a site settings panel may have settings that make sense for certain sites but not for others. In this situation, you can give merchandisers the option of disabling a site settings panel completely for individual sites. To do this, include the following in the config.json file of the extension that creates the panel:

"enableSiteSpecific": true

This setting must appear in top-level array in the file (that is, not within the properties array).

Setting enableSiteSpecific to true adds a checkbox to the panel for specifying whether the settings in the panel are enabled for the current site. The checkbox is initially selected for each site, but a merchandiser can deselect it for individual sites. Deselecting the checkbox disables the panel for a site and causes the fields in the settings panel to disappear for that site. The fields reappear if the merchandiser subsequently selects the checkbox again.