config/style.json

The config/style.json configuration plays a vital role in allowing users of your theme to customise the look and feel of their site. The style.json file settings tap directly into our CSS processor offering property identifiers as variable names

File format

The file must be a valid JSON format in the following structure:

{
    "groups": [
        {
            "title": "Group title",
            "description": "Optional description",
            "properties": [
                {
                    "title": "Property title",
                    "description": "Optional description",
                    "label": "Optional form element label",
                    "id": "identifier",
                    "type": "color",
                    "value": "#fff"
                }
            ]
        }
    ],
    "presets": {
        "Light": {
            "idenifier": "..."
        },
        "Dark": {
            "identifier": "..."
        }
    },
    "preset": "Dark"
}

So let's go through all this in a bit more detail:

groups

A required Array of Objects. Each object represents a grouping of customisable CSS properties and may contain:

description

Optional String description of the group. This is useful if you think your group requires a helpful hint.

properties

Required Array of CSS property objects (described below).

title

Required String property summarising the group of properties that follow. For example "Body Text" or "Headings".


groups.properties

A required Array of CSS properties represented as an Object. Each object may contain the following properties.

connect

Optional Object supported by the font field type used to connect the Font Selector to font-weight and font-style select boxes. This is an object that supports only two properties connect.weight and connect.style. The values for each property must be the unique identifier for the respective fields. For example:

...
    {
        "id": "body_font_family",
        "type": "font",
        "value": "Arial",
        "connect": {
            "weight": "body_font_weight",
            "style": "body_font_style"
        }
    },{
        "id": "body_font_weight",
        "type": "font-weight",
        "value": "400"
    },{
        "id": "body_font_style",
        "type": "font-style",
        "value": "italic"
    }
...
description

Optional String property. Displayed as text between the title and form field within the Theme Customiser.

id

Required String - the unique identifier for the CSS property. The id is used within your presets (described below), but also as a variable name within your CSS files. The id for your property must be an alpha numeric string with no spaces.

label

Optional String property. Displayed as a label below description and above the form field for the CSS property.

options

Object required for select and radio field types. The property names for the options object must be a supported CSS property. The value of each property will be displayed to the user for selection, for example:

...
    {
        "label": "Repeat background?",
        "id": "background_image_repeat",
        "type": "select",
        "options": {
            "no-repeat": "Do not repeat",
            "repeat-x": "Repeat horizontally",
            "repeat-y": "Repeat vertically",
            "repeat": "Repeat everywhere"
        },
        "value": "repeat"
    }
...
title

Optional String property. Displayed as a heading above the form field for this property within the Theme Customiser.

type

Required String representing the type of form element to display to users within the Theme Customiser. Evance accepts the following types:

  • text
    Rendered as a text field.
  • color
    Rendered as a colour selection button. Your value property (below) should be a hexadecimal colour reference including the hash prefix.
  • select
    Rendered as a select box where the user may select a single option (see options).
  • radio
    Rendered as a list of radio buttons where the user may select a single option (see options).
  • font
    Rendered as a textfield and selection button. You may enter any font family supported by Google Fonts (including web safe fonts). Users may also click on the accompanying button to open the Font Selector dialogue. The Font Selector allows the user to choose the Font family, weight and style (normal or italic). Whilst the font family populates the font field, weight and style may be connected to your font-weight and font-style fields (see connect).
  • font-weight
    Rendered as a pre-populated selection list of font weights. Font weight values are presented to the user in both numeric and written formats, however your value should be in CSS supported numeric form ranging from 100 to 900. The font-weight field type may be connected to the Font Selector using the connect property.
  • font-style
    Rendered as a selection list of either normal or italic. Your value should be in CSS supported lowercase format. The font-style field type may be connected to the Font Selector using the connect property.
  • image
    Rendered as a image preview and browse button, which utilises the Media Library to allow users to select an image.
value

Required String default value for the property. This is the global default for this property, but may be overwritten within presets.


presets

Creating a theme is great, but you know what?! People like a choice. Whilst you may prefer a light airy theme, your users may prefer a darker more moody feel. Zero is a good example of a theme with a Light and a Dark preset. Defining presets is really easy.

Presets are Objects where the property name is the name of your preset i.e. Light or Dark. The name of your preset should ideally be one word. In the following example we have two presets Light or Dark. Presets reference only those identifiers within your previously defined group.properties you wish to make part of your preset. This allows users to switch between presets without affecting other customisations.

{
...
    "presets": {
        "Light": {
            "background_color": "#fff"
        },
        "Dark": {
            "background_color": "#333"
        }
    }
...
}


preset

Required String property representing the current preset. When you create your theme this should be your favourite version. So for Zero, we chose Light as our preferred preset. This looks like this:

{
...
    "preset": "Light"
...
}

Using identifiers as variables within your CSS files

The identifiers from your properties are available within CSS files loaded either automatically or via the <ev:css> tag. So let's take a "background_color" identifier and how we use it in a CSS file. It's simply done by wrapping the identifier name with a $(identifier) e.g.:

{
...
    background-color: $(background_color);
...
}

Renders like this:

{
...
    background-color: #fff;
...
}

Read more about CSS Variables