Theme Settings

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 the assets 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.

Available form inputs

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>

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.