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 theme.settings in the layout directory.

When Theme Settings are enabled, the following actions will occur:

  • The theme.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 theme.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.

Enhanced CSS stylesheet syntax

Whenever you use a .css.liquid file extension, the stylesheet is parsed for Liquid tags as mentioned above. This enables you to include standard Liquid tags to add conditional logic and variable substitution into the stylesheet.

In addition, each stylesheet is then parsed using SCSS syntax that supports extensions to the CSS3 standard. Further information on the SCSS extensions can be found at http://sass-lang.com/

SCSS offers many benefits and allows you to simplify complex stylesheets by using variables, nested attributes and mixins.

As an additional benefit, even if you are using only standard CSS syntax, the resulting .css file is compressed so that the file size is reduced to a minimum. This will help your template files to load faster and will result in a better customer experience.

The theme.settings file

Syntax

The theme.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 theme.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 field consists of a single line input field.

A text definition will have the following attributes.

  • label
  • type: text
  • class - Optional CSS class. Special class colour may be used. Defaults to text
  • value - Default value

Here is an example of a text definition. 

email: {
  label: "Email Address<small>This is the address ued by your store</small>",
  type: text,
  value: "info@mydomain.com"
}

Text Area Definitions

A text area field consists of a multiple line input field.

A text area definition will have the following attributes.

  • label
  • type: textarea
  • rows - Optional number of rows in text area. Defaults to 3
  • cols - Optional number of columns in text area. Defaults to 40
  • class - Optional CSS class. Defaults to textarea
  • value - Default value

Here is an example of a text area definition. 

address: {
  label: "Postal Address",
  type: textarea,
  rows: 5
}

Checkbox Definitions

A checkbox field consists of a single checkbox input field.

A checkbox definition will have the following attributes.

  • label
  • type: checkbox
  • class - Optional CSS class. Defaults to checkbox

Here is an example of a checkbox definition. 

use_logo_image: {
  label: "Use a logo?",
  type: checkbox
}

Select Menu Definitions

A select menu field consists of a single drop-down menu field.

A select definition will have the following attributes.

  • label
  • type: select
  • options - A list of options (see below)
  • selected - Optional default selection value
  • class - Optional CSS class. Special select classes may be used. Defaults to select

Options are specified using the options attribute followed by a list of key: value pairs separated by commas and enclosed by […].

The key can be a string of upper and lower-case letters and numbers and may include spaces.

The value must consist of only lower-case letters and numbers. The value must not contain spaces, but may include underscore (_) characters.

For example 

  options: [
    Option1: 1,
    Option2: 2,
    Option3: 3 
  ]

Here is an example of a select definition. 

side_navs_position: {
  label: "Which side for the navigation?",
  type: select,
  options: [
    Display on the left: left,
    Display on the right: right
  ],
  selected: left
}

Radio Button Definitions

A radio button field consists of a set of radio button fields.

A radio button definition will have the following attributes.

  • label
  • type: radio
  • options - A list of options (see below)
  • selected - Optional default selection value
  • class - Optional CSS class. Special classes may be used. Defaults to radio

Options are specified using the options attribute followed by a list of key: value pairs separated by commas and enclosed by […].

For example 

  options: [
    Option1: 1,
    Option2: 2,
    Option3: 3 
  ]

Here is an example of a radio button definition. 

number_of_items: {
  label: "How many items?",
  type: radio,
  options: [
    One: 1,
    Two: 2,
    Three: 3
  ],
  selected: 1
}

File Upload Definitions

A file upload field consists of a single file upload dialog field. The style of this may vary from browser to browser.

A file upload definition will have the following attributes.

  • label
  • type: file
  • name - The name of the uploaded file
  • max_height - Maximum height of the image
  • max_width - Maximum width of the image
  • class - Optional CSS class. Defaults to file

When the file is uploaded, it will be renamed to the name specified by the name attribute. The image will be resized so that the maximum width and height values are not exceeded. The aspect ratio of the image will be preserved. The image type will be converted to match the type specified in the name attribute.

If you do not want the image to be resized, then specify a value of zero for both the max_height and max_width attributes.

Here is an example of a file upload definition. 

logo_image: {
  label: "Upload your logo image",
  type: file,
  name: "logo.png",
  max_height: 80,
  max_width: 900
}

In your Liquid files, you can refer to the various attributes of the uploaded image file as follows:

  • {{settings.key_name}} - Returns the image file name
  • {{settings.key_width}} - Returns the width of the image in pixels
  • {{settings.key_height}} - Returns the height of the image in pixels

Using the above example, a CSS file might look like this: 

{% if settings.use_logo_image %}
#header h1 {
  display: none:
}

#header #logo {
  background: transparent url('{{settings.logo_image_name}}') no-repeat scroll 0 0;
  width: {{settings.logo_image_width}}px;
  height: {{settings.logo_image_height}}px;
}
{% endif %}

Additional Considerations

Creating a theme.settings file

The theme.settings file must be created offline. To do this, download your theme, unpack the zip file and add a theme.settings file to the layout directory.

Once this has been done, you can re-zip the theme directories and upload the new version of the theme.

Once a theme.settings file has been created, it can be edited online using the normal Theme Editor page.

If you are creating a new theme.settings file and there are errors in the file, you may find that the settings form does not appear after you upload the theme. Furthermore, you will be unable to edit the theme.settings file online.

This happens because the system is unable to process the uploaded theme.settings file because of the errors. When creating a new theme.settings file, we recommend that you create only a minimal file, perhaps including only comments then upload it and edit it using the online editor.

If you do this, any errors will be reported when you attempt to save the file, but the theme settings form will not be changed until the error is corrected.

File uploads

All file uploads are placed in the theme's asset directory.

The uploaded files are always renamed to the value of the name attribute in the file definition, and when a file is uploaded, it replaces any file with the same name that already exists.

The uploaded file is also converted to the image format to match the file name extension in the name attribute.

If the uploaded file is not a valid image format, or cannot be converted for whatever reason, an error message will be issued.

A maximum width and height can be specified for a file upload, and if the uploaded image exceeds either of these limits, then the image will be resized so that the maximum dimensions are not exceeded. When resizing the image, the original aspect ratio of the image is preserved.

Special CSS Classes

colour

The colour class can be used in text fields to add a dynamic colour picker to the field. 

text_colour: {
  label: "Text colour",
  type: text,
  class: colour,
  value: "#000000"
}

The variant color may also be used.

font

The font class can be used in select fields to populate the select field with a standard list of CSS font family definitions.

Additional font selections may be added to the standard list by providing an options list. 

text_fonts: {
  label: "Select the text font",
  type: select,
  class: font,
  options: [
    Recommended Fonts: "Arial, Helvetica",
    Alternative Fonts: "Verdana"
  ]
}

collection

The collection class may be used in select or radio field definitions to populate the field with a list of the store's product collections.

If this class is specified, no options attribute is required. 

home_collection: {
  label: "Choose the collection to be displayed on the Home page",
  type: select,
  class: collection,
  selected: home
}

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 as follows 

  {% for product in collections[settings.home_collection].products %}
    <!-- show the product -->
  {% endfor %}

Remember that you only get access to the handle of the collection, not the actual collection itself. This means that you cannot reference the collection as settings.home_collection.products

blog

The blog class may be used in select or radio field definitions to populate the field with a list of the store's published blogs.

If this class is specified, no options attribute is required. 

home_blog: {
  label: "Choose the blog to be displayed on the Home page",
  type: select,
  class: blog,
  selected: home
}

The blog class works similarly to the collection class. 

  {% for article in blogs[settings.home_blog].articles %}
    <!-- show the article -->
  {% endfor %}

  {{ pages[settings.welcome_message].content }}

page

The page class may be used in select or radio field definitions to populate the field with a list of the store's published pages.

If this class is specified, no options attribute is required. 

home_page: {
  label: "Choose the page to be displayed on the Home page",
  type: select,
  class: page,
  selected: home
}

The page class works similarly to the collection class. 

  {{ pages[settings.home_page].content }}

menu

The menu class may be used in select or radio field definitions to populate the field with a list of the store's menus.

If this class is specified, no options attribute is required. 

home_menu: {
  label: "Choose the menu to be displayed on the Home page",
  type: select,
  class: menu,
  selected: main-menu
}

The menu class works similarly to the collection class. 

  {% for link in linklists[settings.home_menu].links %}
  ...
  {% endfor %}

You can also use the nested menu liquid tags to generate multi-level menus. 

  {{ linklists[settings.home_menu].menu_simple }}

or for drop-down menus 

  {{ linklists[settings.home_menu].menu }}

snippet

The snippet class may be used in select or radio field definitions to populate the field with a list of the store's theme snippets.

If this class is specified, no options attribute is required. 

homepage_widget: {
  label: "Choose the widget to be used on the Home page",
  type: select,
  class: snippet
}

The snippet class returns the name of the snippet file that can be used in the Liquid include tag. 

  {% include settings.homepage_widget %}

Using the settings object in Liquid

You can use the settings object in any .liquid files in your theme.

This object is available to all the standard template files that live in the layout and templates directories.

In addition, you can use settings in any text files in your assets directory. In order to do this, rename your existing text file by adding a .liquid suffix to the file name.

For example, we can use Liquid tags and the settings object in a CSS file called theme.css if we rename the file to theme.css.liquid

We can use a similar technique to add Liquid tags to JavaScript files.

As an example, we may want to set the duration of a transition in an image slideshow.

This could be done by adding the following to theme.css.liquid 

  body {
    color: {{ settings.text_color }};
    background-color: {{ settings.bg_color }};
  }

In our slideshow JavaScript slideshow.js.liquid, we might add 

window.addEvent('domready',function(){
  var slideshow = new viewer($('slideshow-images').getChildren(),{
    mode: 'alpha',
    interval: {{ settings.slideshow_interval }},
    onWalk: function(current_index){
    slideshowbuttons.removeClass('active');
    slideshowbuttons[current_index].addClass('active');
  }
});

If you want to allow the user to easily switch between a set of bundled style presets, one option ypu can use is to present a drop-down menu with values corresponding to specialized stylesheets you created in addition to your default stylesheet.

In your theme.liquid you could add 

  {{ 'main.css' | asset_url | stylesheet_tag }}
  {{ settings.color_scheme | asset_url | stylesheet_tag }}

Colour Filters

In order to help you to produce a range of colour schemes for your themes, we've created a set of Liquid Colour Filters that provide a means for you to manipulate a base colour value and produce a wide range of shades and variations on that base colour.

These filters will be most useful in Liquid template stylesheets.

The filters are

  • lighten_by: percent
  • darken_by: percent
  • adjust_brightness: percent (Positive or Negative)
  • adjust_hue: percent (Positive or Negative)
  • adjust_saturation: percent (Positive or Negative)
  • brightness

For example, the following produces a highlight from a given base colour. 

a {
  color: (( settings.base_colour }};
}

a:hover {
  color: {{ settings.base_colour | adjust_brightness: -20 }};
}

The Colour Filters may also be chained together to product complex colour effects.

The brightness level of a colour can be obtained from the brightness filter, which returns an integer between 0 and 100.

More details on Liquid Filters can be found in the Liquid Filter Reference

Additional Notes

  • Any text fields with the color class will produce 6-digit hex codes prefixed with the hash symbol, #dddddd, ready to use in your theme's CSS styles.
  • Checkboxes always produce boolean true/false values which are most useful in if/else statements.
  • You can use all the Liquid logic and control statements in a CSS or JavaScript Liquid template. This means that you can customize your stylesheets and JavaScript as required.
Retrieved from "http://www.spiffystores.com.au/kb/index.php?title=Theme_Settings&oldid=2359"