Theme Settings

From Shopify Wiki

Jump to: navigation, search

Contents

Introduction

Theme settings provide an easy way for any user to customize the look and feel of their shop without having to delve into HTML or CSS code. In order for a theme to be customizable in this way, a couple of things need to be put in place:

  • A settings form built with standard HTML
  • References to the settings object and its properties in your Liquid files.

The form is rendered at the top of the theme editor screen in your shop's admin panel. The name attributes of the various inputs in the form (aside from file uploads, explained below) are mapped directly to properties on the settings object in Liquid.

For example, if a user sets the value of a text field named "text_color" to "#303030", then this value could be used in any layout or template like so: 

  <style>
    body {color: {{ settings.text_color }};}
  </style>

If a user has not yet saved any values through the form, then the defaults are used as defined in the form. This is done through a combination of the value or checked attributes for input tags, the selected attribute for option tags, and the text content of textarea tags.

The settings form

Requirements

The settings form is defined in settings.html, which resides in your theme's config folder. The file doesn't contain the whole form; Shopify takes care of the actual form tag and submit button. Shopify also manipulates the code a bit at render time to make it work well in the admin section.

The form is validated before being saved to make sure it follows a few rules. Most notably, you can't use any javascript and you can't define any custom CSS styles. It is also run through an XML parser to make sure it's a valid XML fragment.

Available form inputs

You can use the following inputs in your form by using standard HTML:

  • Single-line text fields
  • Multi-line text areas
  • Drop-down menus
  • Radio buttons
  • Checkboxes
  • File uploads

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, Shopify will try to convert the uploaded file to the appropriate format (PNG) before saving it. If a user tries to upload a file which Shopify 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 Shopify will resize it accordingly: 

  <input type="file" name="logo.png" data-max-height="200" data-max-width="700" />

Shopify 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 Shopify 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>

Shopify will try to intelligently merge any custom options you provide into the default ones.

Using the settings object in Liquid

The settings object is available to you in any .css.liquid files kept in your assets folder, and this is the ideal place to define user-specified styles.

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.
Retrieved from "http://wiki.shopify.com/Theme_Settings"
Personal tools