Using theme settings

If you want to use the values from your theme settings in your Liquid templates, CSS, and JavaScript files, you must:

• Append the appropriate id attribute to the settings object.
• Amend the filenames.

Appending the id attribute to the settings object

To target the settings you've defined in settings_schema.json, you must add the id attribute of the correct settings input to each occurrence of the settings Liquid object.

For example, you might have a text input in settings_schema.json that looks like this:

{
  "type":      "text",
  "id":        "tagline",
  "label":     "Your company tagline",
  "default":   "So fresh, so clean!",
  "info":      "Use this field to add a tagline to your shop",
},

The value of this text input can be output using the following format in your Liquid templates:

{{ settings.tagline }}

Amending filenames of CSS or JavaScript files

If you want your CSS or JavaScript files to access the global settings object, you must append a .liquid extension to their file names.

For example, if you have a stylesheet named style.css, change it to style.css.liquid. You can then target the setting in the same way you would for a template file:

.banner {
  background-color: {{ settings.bg_color }};
}

Special-case user selections

There are some special cases for handling certain setting selections:

• None
• Non-existent or hidden

Handling the selection of the option "None"

A theme will rarely call on a hard-coded page, collection, or blog. Instead, they typically look at the theme editor. So, you would not see objects being loaded like this:

{% for product in collections.frontpage.products %}
  {% include 'product-grid-item' %}
{% endfor %}

Instead, you would load a page, collection, or blog selected through the settings object:

{% for product in collections[settings.fp_collection].products %}
  {% include 'product-grid-item' %}
{% endfor %}

You can also set a theme setting to None:

This does not return a string with the value None. Instead, it returns an empty string in your theme's config/settings_data.json file:

"fp_page": "",

To determine if the theme setting for the page, blog, or collection is empty, compare the appropriate settings attribute to blank as follows:

{% if settings.fp_page == blank %}
  <!-- The merchant does not want to add a page here. His fp_page theme setting was set to None. -->
{% endif %}

An unless statement also works:

{% unless settings.fp_page == blank %}
  {% assign page = pages[settings.fp_page] %}
  <h1>{{ page.title }}</h1>
  <div>{{ page.content }}</div>
{% endunless %}

The example below would not work, as empty strings are truthy in Liquid. If your settings.fp_page is an empty string, then {% if settings.fp_page %} will be true, resulting in empty elements on the page:

Input

{% if settings.fp_page %}
  {% assign page = pages[settings.fp_page] %}
  <h1>{{ page.title }}</h1>
  <div>{{ page.content }}</div>
{% endif %}

Output

<h1></h1>
<div></div>

Handling the selection of non-existent or hidden settings

There might be cases where a theme setting is set to an object that used to exist, but has since been deleted or hidden. A theme can't tell the difference between a hidden resource and one that does not exist.

For example, you might have a theme setting that's set to frontpage:

"fp_page": "frontpage",

After this is set, the frontpage page could be deleted or hidden by the merchant. You can account for this situation by performing two checks:

{% assign front_page = settings.fp_page %}
{% unless pages[front_page] == empty %}
  <h1>{{ page.title }}</h1>
  <div>{{ page.content }}</div>
{% endunless %}

This first checks if the theme setting is set to a value that is not blank, then checks if it's still accessible in the store.

###Before text output

Before outputting a text setting, check if the text is not blank:

{% assign heading = settings.heading %}
{% unless heading == blank %}
  <h1>{{ heading }}</h1>
{% endunless %}

You can force default text by using the default Liquid filter:

<h1>{{ settings.heading | default: 'Featured heading' }}</h1>

If settings.heading is left blank, 'Featured heading' will be outputted - otherwise the value of settings.heading will be outputted.

Before page content output

Before outputting a page's title, check that a page exists with the selected handle, and that the page title is not blank:

{% assign page = pages[settings.fp_page] %}
{% unless page == empty and page.title == blank %}
  <h1>{{ page.title }}</h1>
{% endunless %}

Before collection output

Before outputting products in a collection, check that the collection exists:

{% assign collection = collections[settings.collection] %}
{% unless collection == empty %}
  {% for product in collection.products %}
    {% include 'product-item' %}
  {% endfor %}
{% endunless %}

Detecting the theme editor with JavaScript

From Liquid

The request.design_mode global variable can be used in your theme's Liquid files to detect whether the storefront is being viewed in the theme editor. The value of the variable is set to true when viewing the theme editor, otherwise it is set to false.

{% if request.design_mode %}
  <!-- This will only render in the theme editor -->
{% endif %}

From JavasScript

The Shopify.designMode global variable can be used in your theme's JavaScript files to detect whether the storefront is being viewed in the theme editor. The value of the variable is set to true when viewing the theme editor, otherwise it is set to undefined.

if (Shopify.designMode) {
  // This will only happen in the theme editor
}