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.settingsfile 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
settingsobject will be used to provide substitution values for all the standard Liquid templates. - Additionally, any files with a suffix of
.liquidresiding in theassetsdirectory will be processed for Liquid tags, and the corresponding file without the.liquidsuffix 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
colorclass 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.