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": { "title": "Abandoned Cart Settings", "description": "Configuration options for Abandoned Cart email and Cart idle webhook functionality.", "emailCountdownLabel": "Days until email is sent", "cartMinValueLabel": "Minimum amount", "cartMinValueHelpText": "Minimum value for an Abandoned Cart email.", "webhookCountdownLabel": "Minutes until webhook is triggered" } }
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:
{ "titleResourceId": "title", "descriptionResourceId": "description", "properties": [ { "id": "emailCountdown", "type": "numberType", "helpTextResourceId": "", "labelResourceId": "emailCountdownLabel", "defaultValue": 7 }, { "id": "minimumCartValue", "type": "stringType", "helpTextResourceId": "cartMinValueHelpText", "labelResourceId": "cartMinValueLabel", "pattern": "^[0-9]+(\\.[0-9]{2})?$" }, { "id": "webhookCountdown", "type": "numberType", "helpTextResourceId": "", "labelResourceId": "webhookCountdownLabel", "minValue": 1, "defaultValue": 20 } ] }
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, “Abandoned Cart Settings” in the illustration above. The descriptionResourceId
property specifies a key for the descriptive text that appears below the title, “ Configuration options for Abandoned Cart email and Cart Idle webhook functionality” in the illustration above.
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
, numberType
, multiSelectOptionType
, and so on. Both the standard keys and the data types are described in full detail in Define a widget’s configurable settings.