Overview

To make it easier for merchants to customize your theme, you can use JSON to create settings that merchants can access through the theme editor.

You can provide settings at the theme, section, or block level. Settings can be fixed (such as informational elements) or interactive (such as a drop-down menu). Setting values can be static, or use dynamic sources to render contextually appropriate values.

Exposing settings makes your theme more customizable so it can better express a merchant's brand. It also can make your theme more flexible so that you can address various use cases for merchants.

Subtypes

There are two categories of settings:

Location

You can create settings in the following places:

• config > settings_schema.json
• Section files in the sections folder and may use the section's {% schema %} tag

└── theme
    ├── config
    |   ├── settings_schema.json
    |   ...
    ├── sections
    |   ├── product_detail.liquid
    |   ├── collection_detail.liquid
    |   ...
    ...

settings_schema.json

The settings_schema.json file controls the content of the Theme settings area of the theme editor. Settings in this file translate to global theme settings, which can be accessed through the Liquid settings object.

Section schema

The section {% schema %} tag is where you can create section settings and block settings. Those settings can be accessed through the settings attribute of the section object and block object, respectively.

Schema

Settings are defined as a JSON settings attribute that's parented to the object that the settings apply to. This attribute accepts an array of settings.

{
  ...
  "settings": [
    {
      "type": "checkbox",
      "id": "show_thumb_mb",
      "label": {
        "zh-CN": "开启移动端缩略图",
        "en-US": "Enable mobile thumbnails"
      },
      "default": true
    },
    {
      "type": "checkbox",
      "id": "zoom_on",
      "label": {
        "zh-CN": "悬停放大图片",
        "en-US": "Hover to zoom image"
      },
      "info": {
        "zh-CN": "仅在桌面端悬停图片时有效",
        "en-US": "Only works when hovering images on desktop"
      },
      "default": false
    },
  ]
  ...
}

Usage

When working with settings, you should familiarize yourself with the following:

• Accessing setting values
• Checking the setting value format
• Using dynamic sources for settings
• Platform-controlled settings

Access settings

Depending on where they were created, you can access settings through the following Liquid objects:

• The global settings object
• The section object
• The block object

To access a specific setting, append the id attribute of the associated setting to the object that you want to access.

For example, if you had the following setting implemented in each Liquid object:

{
  "type": "text",
  "id": "title",
  "label": "Title",
  "default": "Featured"
}

Then the following Liquid would generate the following output:

<!-- Settings -->
Title: {{ settings.title }}

<!-- Section -->
Title: {{ section.settings.title }}

<!-- Block -->
Title: {{ block.settings.title }}

<!-- Settings -->
Title: Featured

<!-- Section -->
Title: Featured

<!-- Block -->
Title: Featured

Check the format of the setting value

When referencing settings, you should always check that the value is in the format that you expect. Any setting without an automatic default value could end up with no value, which translates to an empty string.

For example, if you have a setting with an id of title, then the following Liquid would generate the following output depending on the value:

<!-- No value -->
Title: {{ settings.title }}

<!-- With value -->
Title: {{ settings.title }}

<!-- No value -->
Title:

<!-- With value -->
Title: Featured

You can check whether a value is an empty string with the blank operator. For example:

{% unless settings.title == blank %}
  {{ settings.title }}
{% endunless %}

Resource-based settings

To avoid an empty string, check that the value is in the format that you expect. It's possible that no resource was selected, the selected resource no longer exists, or the selected resource has been hidden.

For example, if you have the following page type setting:

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

Then you can check for emptiness like the following:

{% if section.settings.page != blank %}
  {{ section.settings.page.title }}
  {{ section.settings.page.url }}
{% else %}
  No page, or invalid page, selected.
{% endif %}

Dynamic sources

Settings for sections and blocks included in a Liquid template have the option for merchants to connect one or more dynamic sources to the setting, depending on the setting type.

Learn more about dynamic sources.

Platform-controlled settings

In the theme editor, Shoplazza exposes a custom CSS setting at the theme level.