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.
The Storefront endpoint also allows you to hide a setting or a property, such as creating a custom payment setting that should not be displayed on your storefront, or allowing a setting that you might not want customers to see to be sent to the storefront. By default, all properties are exposed in the Storefront endpoint, but you can use the public
property to identify properties or settings that should not be displayed by setting the property to "public": false
. Note that the public property does not work for password fields. The password field type, while visible in the site settings, will not function correctly, and is only applicable in custom payment 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.