Settings.json

Within the theme editor, individual settings can be configured to be made available in the following places:

1. From a Theme settings section (shown at the top of the sidebar on every page)
2. From a Header settings section (shown on the sidebar on every page)
3. From a Page settings section (shown on the sidebar on the defined page types)
4. From a Footer settings section (shown on the sidebar on every page)

Each individual setting is declared in settings.json separately, but settings must be grouped into sections.

Setting sections consist of:

• title the name of the setting section
• description (optional) a description of the settings contained within the section
• help (optional) containing url (required)
• icon (optional) which icon to display for the setting section. See the full list of available icons
• resettable (optional) set to true to display a reset button for the section group so users can reset to theme defaults
• settings an array of the settings available
• type (optional) can be set to header, footer or page_settings - where no type is set, the setting section will appear in theme settings
• pageTypes (optional), for use with type of page_settings, an array of pageTypes. See the full list of page types
• group (optional) can be a string up to 50 characters. It can be used to group setting sections

An example setting section declaration:

A maximum of 75 setting sections can be declared.

Individual settings are declared within the settings array within a setting section or within a section or block (when declared in theme.json).

Each section can contain a maximum of 250 individual settings.

Settings consist of:

• name the name of the setting (as referenced in theme files)
• type the type of setting, see below
• label the setting field label as displayed in the theme editor
• note optional additional helper text to display to users
• defaultValue what the default value of the setting is (used when the theme is installed or setting reset)
• livePreview set to true or cssCustomProperty to indicate to the theme to update the live preview in real time, without page refresh
• separator set to true to add a separator line between the setting and the setting beneath
• refreshButton set to true to display a refresh link next to the setting label (can be used to prompt users to click outside the field where live preview is not available)
• requiredApp or requiredExtension use an app name to declare whether the setting should only be visible for users with an app installed (e.g. product tabbed descriptions)
• triggerButton set to display an 'enable popup' button to appear with the setting, e.g. "triggerButton": "Trigger popup in preview"

Additional properties are available for settings of a certain type (as declared below).

The following setting types are valid. Some setting types require additional properties set within the setting.

Renders a simple text field.

Renders a text area field.

Renders a text area field that has rich text editing buttons (link, bold, italic, underlined, font size). Set a property of extraButtons to true for additional buttons (colour, paragraph/headings, font alignment and full screen mode).

Renders a simple check box.

Renders a radio button selection. Set values for the radio button using the values array, e.g.

Renders a drop down selection. Set values for the drop down using the values array, e.g.

Renders a drop down for the user to select from a platform configured link list.

On installation of the theme, the link list is created and designated to the theme. Links defined in a links array are automatically created within the link list.

A property of link_list_position can be set to provide instructions to users on where the link list appears. By default, link lists can have titles (which acts as the menu title), set a disableTitle property (optional) to true to prevent users from adding or editing a title for the link list (to improve usability).

Renders a drop down of payment gateways available on the platform for the account's location.

Enables a font selection to be made from a list of fonts (available through the Google Font platform). Fonts are displayed in a special type of selection, rendered by the platform.

A 'theme default' choice is available at the top of the selection. When no font is selected, the interface will display Theme Default as the selected font and the setting property returns empty on the theme.

Renders a colour picker.

Use a colorGroup property to group similar colours together (e.g. all colour settings relating to the header can be grouped in the header).

defaultValue must include the # at the beginning of the hexadecimal colour reference.

A separate colourGroups array is available. A property of global can be set to true to indicate the theme's global colour settings.

Renders a slider setting.

Additional properties available:

minValue the lowest value available on the slider maxValue the highest value available on the slider step the increment value valueSuffix any suffix that should be outputted at the end of the value rendered by the setting

Renders a logo setting.

The user can upload a logo which is rendered on the theme using the global.business.logo_url variable.

Only one instance of this setting should be set.

Renders a favicon setting.

The user can upload an image file which is rendered as a favicon on the theme. The platform outputs the favicon using global.header.

Renders a single image setting.

Renders a drop down for the user to select from a platform configured gallery.

On installation of the theme, the gallery is created and designated to the theme. Images defined in an images array are automatically created within the gallery.

The disableTitle property can be set to true on a gallery setting to remove the ability for users to change the name of the gallery.

disableImageText and disableImageURL can be set to true to prevent users from entering gallery image text and/or URLs.

Renders a drop down of the active and inactive leaf categories on the ShopWired account.

Renders a drop down of the active and inactive parent categories on the ShopWired account.

Renders a drop down of the active and inactive products on the ShopWired account.

Renders a drop down of website pages on the ShopWired account. The selected website page can be rendered on the twig view using the ID.

Renders a drop down of blog posts on the ShopWired account. The selected blog post can be rendered on the twig view using the blog post ID.

Settings can be rendered in Twig templates and SCSS files.

• In Twig templates
• All theme settings are rendered through the global.theme.settings property (which is commonly shortened to gts on themes)
• All section and block settings are rendered through the appropriate properties, e.g. section.settings.abc and block.settings.abc
• In SCSS files
• Settings are rendered in SCSS files, e.g. $color_home_category_browse_border

The theme's live preview utilises a separate instance of the compiled theme.css file (separate to the file utilised on your website). Whilst recompilation of theme.css when viewing the website live is triggered on any change, this is not the case in the website displayed in the live preview.

SCSS is only recompiled when a certain 'event' occurs:

• when a google_font setting is changed
• when a color_group_checkbox setting is changed
• when a color setting is changed
• when a setting having livePreview set to cssCustomProperty is changed

Additionally, recompilation can be triggered to occur with an additional property for a setting.

Set scssVariable to true to ensure that recompilation occurs when the setting is changed.

Recompilation can, however, be forced by selecting the refresh button in the browser.