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.