Overview​

To simplify theme customization for merchants, you can use JSON to create settings that they can access through the Theme Editor.

Settings can be provided at the theme, section, or block level. These settings can be fixed (e.g., informational messages) or interactive (e.g., dropdown menus). The values for settings can be static or use dynamic data to display context-appropriate values.

Changing settings makes your theme more customizable, allowing merchants to better express their brand. It also makes your theme more adaptable, enabling it to handle a variety of use cases for merchants.

Types of Configuration Options​

There are two main types of configuration options:

• Input Settings - Can save a value and be configured by the merchant.
• Sidebar Settings - Cannot save values and are not configurable. They are informational elements used to display tips and group information for configuration options.

Locations​

You can create settings in the following locations:

• config > settings_schema.json
• Section files, using the section's {{#schema}} helper

└── theme
    ├── config
    |   ├── settings_schema.json
    |   ...
    ├── sections
    |   ├── main_product.html
    |   ├── another_section_file.html
    |   ...
    ...

settings_schema.json​

The settings_schema.json file controls the content of the theme settings area in the Theme Editor. The settings in this file become global theme settings, which can be accessed via the Handlebars settings object.

Section schema​

The {{#schema}} helper in sections is where you can create section settings and block settings. These settings can be accessed via the settings property of the section object and the block object.

Schema​

Settings within the Section Schema can be defined as an array of configuration options using the settings property.

{
  ...
  "settings": [
    {
      "type": "text",
      "id": "shopline_text",
      "label": "Example text",
      "default": "Input text"
    },
    {
      "type": "url",
      "id": "shopline_url",
      "label": "URL",
      "default": ""
    }
  ],
  ...
}

Usage​

When using settings, you need to be familiar with the following:

• Translating Settings
• Accessing Configuration Values
• Checking the Format of the Setting Value
• Resource-Based Settings
• Using Dynamic Sources
• Platform-Controlled Settings

Translating Settings​

You can translate the various attributes of configuration options according to the active language of the online store. These translation details are stored in the schema localization file.

Accessing Configuration Values​

You can access settings through three different Handlebars objects, depending on where they are created.

• Global configuration object
• Section object
• Block object

To access a specific setting, append the id attribute of the relevant setting to the object you are accessing. For example, if you have the following setting implemented in each Handlebars object:

{
  "type": "text",
  "id": "example_text",
  "label": "Text",
  "default": "Default text."
}

Then the following Handlebars code will generate the following output:

// Settings
Text: {{ settings.example_text }}
// Section
Text: {{ section.settings.example_text }}
// Block
Text: {{ block.settings.example_text }}

Output:

// Settings
Text: Default text.
// Section
Text: Default text.
// Block
Text: Default text.

Checking the Format of the Setting Value​

When referencing settings, you should always check that the value is in the expected format. Any setting without an automatic default value may end up having no value, which will be converted to an empty string. For example, if you have a setting with an id of example_text, then the following Handlebars code will generate the following output based on the value:

// No value
Setting: {{ settings.example_text }}
// With value
Setting: {{ settings.example_text }}

Output:

// No value
Setting:
// With value
Setting: Default text.

You can use if helper to check if the value is an empty string. For example:

{{#if settings.example_text}}
  {{settings.example_text}}
{{/if}}

Resource-Based Settings​

To prevent empty strings, verify that the value is in the expected format. The issue could be that no resource is selected, the selected resource no longer exists, or the selected resource has been hidden. For example, if you have the following page_picker type setting:

{
  "type": "page_picker",
  "id": "page",
  "label": "Page"
}

Then you can check if it is empty as follows:

{{#if settings.page}}
  {{ settings.page.title }}
  {{ settings.page.content }}
{{else}}
  No page selected, or the selected page is invalid.
{{/if}}

Legacy Resource-Based Settings​

Previously, resource-based settings returned the handle of the associated resource, requiring you to use that ID to access the actual object through Handlebars. For example, if you have the following page_picker type setting:

{
  "type": "page_picker",
  "id": "page",
  "label": "Page"
}

Then you can check if it is empty as follows:

{{#if settings.page}}
  {{assign 'page' (get settings.page pages) }}
  {{ page.title }}
  {{ page.content }}
{{else}}
  No page selected, or the selected page is invalid.
{{/if}}

Dynamic Sources​

For sections and blocks included in JSON templates, merchants can choose to connect one or more dynamic sources to a setting, depending on the setting type.

Learn more about dynamic sources.

Platform-Controlled Settings​

In the template editor, SHOPLINE exposes custom CSS settings at the template and block levels. You cannot add or hide this setting in the settings schema.

Any custom CSS added by the merchant using this setting is stored in properties, either in the custom_css attribute of the JSON template's section or in the settings_data.json platform_customizations object.

This setting is designed to enable users to customize the appearance of their storefront without modifying the template code. As a template developer, you should neither add this setting nor alter its value once it has been set. Instead, use dedicated CSS assets and the stylesheet Handlebars tag, incorporating CSS customization options through these theme settings.