Theme Settings
From Spiffy Stores Knowledge Base
Introduction
Spiffy Stores provides a very powerful template tool that can be used to create a wide variety of complex themes.
However, for many users, who don't want to design and build their own themes, there has been no simple way to customize a theme without having to modify the HTML and CSS code.
The current support for themes has now been enhanced to enable a theme settings configuration file to be added to any theme which will provide simple customization options for the end-user.
Theme Settings are enabled when a theme contains the file layout.settings
in the layout
directory.
When Theme Settings are enabled, the following actions will occur:
- The
layout.settings
file will be parsed for all the settings definitions. - A form will be built from these definitions and will be displayed as part of the 'Theme Editor' page.
- The user can choose the settings that are appropriate for their needs and save them.
- The
settings
object will be used to provide substitution values for all the standard Liquid templates. - Additionally, any files with a suffix of
.liquid
residing in theassets
directory will be processed for Liquid tags, and the corresponding file without the.liquid
suffix will be generated. This can be ued to generate CSS and JavaScript files from Liquid templates.
The form rendered at the top of the Theme Editor page contains a number of input fields an controls that are defined in the layout.settings
file.
Each field in the settings file is mapped to a settings
object attribute.
For example, the definition
address1: { label: "Address Line 1", type: text, value: "Address Line 1" }
will map directly to the settings.address1
attribute, and can be referred to in any Liquid template as
<li>{{ settings.address1 }}</li>
Default values can be defined in the settings file and these values are used when the user has not saved their own preferences.
The layout.settings file
Syntax
The layout.settings
file contains all the definitions for your theme settings.
The file contains comments, parts, sections and definitions. You can use spaces to format the file, but they are not significant, except within strings.
This is a sample layout.settings
file:
# # This is a sample Theme Settings file # # Field Types - text, textarea, select, radio, checkbox, file, # [Description] This is a description of the theme settings, where you can include any special instructions for the user. You can include as many lines of description as you require. [Settings] Section: [Theme colours] main_colour: { label: "Site header & buttons", type: text, class: colour, value: "#7ACF00" } Section: [Add your logo] use_logo_image: { label: "Use a logo?", type: checkbox } logo_image: { label: "Upload your logo image", type: file, name: "logo.png", max_height: 80, max_width: 900 } Section: [Side menu] navigation_colour: { label: "Side menu colour<small>This setting controls the colour of the navigation the side (not the top menu)</small>", type: text, class: colour, value: "#7ACF00" } side_navs_position: { label: "Which side would you like to display the side navigation on?<small>By default, the side navigation appears on the right hand side. Choose 'Display on the left' if you would prefer to have it on the left side</small>", type: radio, options: [ Display on the left: left, Display on the right: right ], selected: left } display_latest_news: { label: "Display the 'Latest news' section?<small>Un-tick this box if you want to hide the 'Latest news' section that appears in the side menu</small>", type: checkbox } display_items_count: { label: "Select the number of items to display", type: select, options: [ none: 0, 1: 1, 2: 2, 3: 3, 4: 4, 5: 5, max: 10 ], selected: 10 }
Comments
Any line can start with a '#' character, and this line will be treated as a comment and ignored.
Parts
The input file is divided into parts.
Each part starts with the line
[Part Name]
Description Part
The theme settings description part starts with the line
[Description]
The rest of the part is treated as free-form text, with paragraphs being broken by one or more blank lines.
Settings Part
The theme settings main part starts with the line
[Settings]
The rest of the part contains a number of sections.
Sections
The Settings
part contains one or more sections.
Each section starts with a line
Section: [Section Name]
Each section groups together a set of similar definitions, and all the settings in a section are displayed together in the Theme Editor form surrounded by a border, with the Section Name
used as a caption.
Definitions
Each definition has the following form
name: { label_1: value_1, label_2: value_2, ... label_n: value_n }
The name
of the definition maps directly to the Liquid variable settings
attribute. In this case, the value of definition name
is referenced in Liquid as settings.name
All definitions will have a label
attribute. This is used to display a prompt in the form for each input definition. The value is a quoted string. In addition, you can use the tags <small> … </small>
to include text that is formatted in small text underneath the label.
test_definition: { label: "Enter the test value<small>The test value is always an integer</small>" ... }
Text Definitions
A text definition will have the following attributes.
- label: "The label string is used as a prompt for the value"
You can use the following inputs in your form by using standard HTML:
- Single-line text fields *NOTE* Make sure the empty value field is present.
<tr> <th><label for="my_text">Name of this setting.</label></th> <td><input type="text" id="my_text" name="my_text" class="text" value=""/></td> </tr>
- Multi-line text areas *NOTE* Make sure the empty value field is present.
<tr> <th><label for="my_textarea">Name of this setting.</label></th> <td><input type="textarea" rows="4" cols="20" id="my_textarea" name="my_textarea" class="textarea" value=""/></td> </tr>
- Drop-down menus
<tr> <td><label for="my_dropdown">Name of this Setting</label></td> <td> <select name="my_dropdown" id="my_dropdown"> <option value="1" selected="selected">1</option> <option value="2">2</option> <option value="3">3</option> <option value="4">4</option> </select> </td> </tr>
- Radio buttons
- Checkboxes
<tr> <td><label for="my_checkbox">Name of this Setting</label></td> <td><input type="checkbox" id="my_checkbox" name="my_checkbox" value="1" /></td> </tr>
- File uploads
<tr> <td><label for="my_img">Settings Name</label></td> <td> <input type="file" id="my_img" name="my_img.jpg" data-max-width="100" data-max-height="200" /> </td> </tr>
Things to consider
Checkboxes
The values of checkboxes are always forced to be "1", and hidden fields are inserted for each checkbox to allow for "false" values to be submitted appropriately.
File uploads
File uploads always go to the theme's asset folder. The name of the saved file is not determined by the original name of the user's uploaded file, but rather is equal to the name attribute of the file input tag. For example, a file uploaded through this input would always be saved as a theme asset called logo.png:
<input type="file" name="logo.png" />
Furthermore, since the name has an image file extension, Spiffy Stores will try to convert the uploaded file to the appropriate format (PNG) before saving it. If a user tries to upload a file which Spiffy Stores cannot convert to PNG (such as an SWF file), they will get an error telling them so.
You can also specify a maximum height and width for an image upload and Spiffy Stores will resize it accordingly:
<input type="file" name="logo.png" data-max-height="200" data-max-width="700" />
Spiffy Stores will then maintain the aspect ratio of the uploaded image while constraining it to those maximum dimensions.
Special CSS classes you can use
color
Add the color
class to a text field and Spiffy Stores will turn it into a dynamic javascript-driven color picker:
<input name="text_color" class="color" type="text" value="#332211" />
font
The font
class can be applied to a select
tag to populate it with a standard list of web-safe CSS font family definitions for the user to select using concise and readable names:
<select class="font" name="header_font" id="header_font"> <option value="Georgia, Utopia, 'Times New Roman', Times, serif" selected="selected">Georgia</option> </select>
Spiffy Stores will try to intelligently merge any custom options you provide into the default ones.
collection
The collection
class can be applied to a select
tag to populate it with a list of the shop's product collections.
<select class="collection" name="frontpage_collection" />
The collection handles become the option values, while the full collection names are used for the option labels. This means that you can access the selected collection in Liquid like so:
{% for product in collections[settings.frontpage_collection].products %} <!-- show the product --> {% endfor %}
Note that it is the collection's handle which gets exposed to Liquid, not the collection itself. The handle is just a string which we're using as a key for the collections
object, so settings.frontpage_collection.products
would not return anything useful.
blog & page
The blog
and page
classes can be applied to select
tags to populate them with lists of the shop's blogs or pages.
<select class="blog" name="main_blog" /> <select class="page" name="welcome_message" />
These work pretty much like the collection
selectors:
{% for article in blogs[settings.main_blog].articles %} <!-- show the article --> {% endfor %} {{ pages[settings.welcome_message].content }}
snippet
The snippet
class can be applied to a select
tag to populate it with a list of the current theme's snippets.
<select class="snippet" name="sidebar_widget" />
The value exposed to liquid is the name of the snippet without the .liquid
extension, so it is perfect for using directly in an include tag:
{% include settings.sidebar_widget %}
Using the settings object in Liquid
The settings object is available to you in any .liquid
files kept in your layout
, templates
, snippets
, or assets
folders. A .css.liquid
file in assets
is the ideal place to define user-specified styles. JavaScript files can use theme settings as well — for example to set the duration of a transition in an image slideshow.
For example, in main.css.liquid
:
body { color: {{ settings.text_color }}; background-color: {{ settings.bg_color }}; }
If you want to allow the user to easily switch between bundled style presets, one option is to present a drop-down menu with values corresponding to specialized stylesheets you have created in addition to your main stylesheet.
In your settings.html
:
<select name="color_scheme"> <option value="ocean.css">Ocean</option> <option value="forest.css">Forest</option> <option value="solar.css">Solar</option> </select>
In your theme.liquid
:
{{ 'main.css' | asset_url | stylesheet_tag }} {{ settings.color_scheme | asset_url | stylesheet_tag }}
Some other things to keep in mind:
- Any text fields with the
color
class will produce 6-digit hex codes prefixed with the pound (#) symbol, ready to use in your theme's CSS styles. - Checkboxes always produce boolean true/false values which are most useful in if/else statements.
- If you edit a settings form on a live site, make sure that any textareas you add have a default value or the parser can fail to render the form correctly in the admin.