Working with other theme files
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 or to the section.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 }}
Appending the id attribute to the section.settings object
To target the settings you've defined in a section's {% schema %}
node, you must add the id
attribute of the correct settings input to each occurrence of the section.settings
Liquid object.
For example, you might have a radio button input in header.liquid
that looks like the following:
{
"type": "radio",
"id": "logo_alignment",
"options": [
{ "value": "left", "label": "Left"},
{ "value": "center", "label": "Centered"}
],
"label": "Logo alignment"
}
The value of this radio button input can be output using the following format in your section:
{{ section.settings.logo_alignment }}
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:
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
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
}