Support Center

About Koken

This Help Center provides support for Koken, a free content management system designed for photographers, artists and designers.

Settings

Settings

Last Updated: May 31, 2014 03:49PM EDT

Settings allow publishers to edit a theme's appearance in the site console. This walkthrough will explain how to incorporate settings into your theme.

Create a setting

Let's demonstrate how settings work with a basic example. We're going to allow publishers to control whether tagline text is published in the header. We start by adding a settings region to the theme's info.json file. This region will define all settings throughout the theme. For example:

{
  "name": "Theme name",
  "version": "1.0",
  "description": "Brief description of this theme",
  "demo": "http://yoursite.com/demo",
  "author": {
  "name": "Your name",
  "link": "http://yoursite.com"
  },

  "settings": {

  }
}

Next step is to add a settings group inside. We create groups to organize related settings together. When loaded in the site console, the settings will appear underneath the group's name and assigned icon. Common examples for groups include "Typography", "Color", "Page", etc., but you can name the group anything you want. For the purposes of this walkthrough we'll name ours "Layout". Example:

"settings": {
  "Layout": {
    "icon":"layout",
    "settings": {

    }
  }
}

As you can see above, Layout contains two properties: "icon" and "settings".

icon controls the icon displayed next to the group's name in the settings panel. Available options include "style", "source", "info", "page", "links", "type", "layout", "misc", "nav", "slideshow", "theme", "img" "color", "plugin", "social" "discuss", "playback", "dimensions", "mobile" and "transition".

Next up is another settings region. This is where we define the group's settings. Example:

"settings": {
  "Layout": {
    "icon":"layout",
    "settings": {
      "show_tagline": {
        "label": "Show tagline",
        "type": "boolean",
        "value": true
      }
    }
  }
}

There are a few things going on here so let's take it line by line.

We first define the setting with a unique name, in this case show_tagline. Inside we add properties for label, which is how the setting will be labeled in the console's settings panel, type which establishes the type of setting it is, and value which is the setting's default value.

To add a second setting to the Layout group insert a comma at the end of show_tagline, then create another setting, like so:

"settings": {
  "Layout": {
    "icon": "layout",
    "settings": {
      "show_tagline": {
        "label": "Show tagline",
        "type": "boolean",
        "value": true
      },
      "show_footer": {
        "label": "Show footer",
        "type": "boolean",
        "value": true
      }
    }
  }
}

With our tagline setting defined it's time to use it in a template. Whenever you use a setting in a template you take the setting's name (in this case, show_tagline) and preface it with settings. The example below demonstrates this by using a <koken:if> template tag to test whether the setting is true or false:

<koken:if true="settings.show_tagline">
  {{ site.tagline }}
</koken:if>

Use settings in CSS

We've explained how settings are used in a .lens template, but what about a CSS document? Yes, you can output setting values to CSS as well. Here's how.

<html>
  <head>
    <koken:settings />
  </head>
  <body>
  </body>
</html>

When parsed, Koken will load /css/settings.css.lens into the theme.

When using setting values in CSS, prepend the setting's variable name with $. Here's an example that assigns the value of a color picker to control the background color of the page.

body {
  background-color:$bg_color;
}

If the setting's variable conflicts with other CSS markup, like "px", wrap the setting in brackets, like so:

body {
  background-color:$bg_color;
  font-size:[$bg_font_size]px;
}

If a setting uses scoped_values (see below) and you need to access the values passed to each scoped template, you can do that in CSS by appending the template's name to the end of the setting. For example:

#albums {
  margin:[$page_margin.albums]px;		
}

Create dependencies between settings

Setting visibility may be toggled on/off based on the value of another setting. This improves usability by only displaying settings that will actually do something. Do this by adding a dependencies member to your settings. Here's an example:

"settings": {
  "Group": {
    "icon": "layout",
    "settings": {
      "setting_one": {
        "label": "Label",
        "type": "boolean",
        "value": true
      },
      "setting_two": {
        "label": "Label",
        "type": "boolean",
        "value": true,
        "dependencies": {
          "evaluate": "all",
          "conditions": [
            {
              "option": "setting_one",
              "equals": true
            }
          ]
        }
      }
    }
  }
}

In the example above we create a dependency between setting_one and setting_two. If setting_one has a value of true (checked), setting_two is displayed in the settings panel. If setting_one is false, setting_two is hidden.

To create a dependency that displays when another option is not a particular value, use "not" instead of "equals".

"settings": {
  "Group": {
    "icon": "layout",
    "settings": {
      "setting_one": {
        "label": "Label",
        "type": "select",
        "options": [
          { "label": "None", "value": "none" },
          { "label": "Red", "value": "red" },
          { "label": "Blue", "value": "blue" }
        ]
        "value": "none"
      },
      "setting_two": {
        "label": "Label",
        "type": "boolean",
        "value": true,
        "dependencies": {
          "evaluate": "all",
          "conditions": [
            {
              "option": "setting_one",
              "not": "none"
            }
          ]
        }
      }
    }
  }
}

If you include more than one condition, and "all" is assigned to evaluate, every condition must be true. Change evaluate to "any" if one true condition is enough.

"settings": {
  "Group": {
    "icon": "layout",
    "settings": {
      "setting_one": {
        "label": "Label",
        "type": "boolean",
        "value": true
      },
      "setting_two": {
        "label": "Label",
        "type": "boolean",
        "value": true
      },
      "setting_three": {
        "label": "Label",
        "type": "boolean",
        "value": true,
        "dependencies": {
          "evaluate": "any",
          "conditions": [
            {
              "option": "setting_one",
              "equals": true
            },
            {
              "option": "setting_two",
              "equals": true
            }
          ]
        }
      }
    }
  }
}

If all settings within a group have the same dependency you may assign a dependency to the group itself, as shown below. All of the settings in GroupTwo will appear if setting_one is true. Otherwise they'll be hidden from the panel.

"settings": {
  "GroupOne": {
    "icon": "layout",
    "settings": {
      "setting_one": {
        "label": "Label",
        "type": "boolean",
        "value": true
      }
    }
  },
  "GroupTwo": {
    "icon": "layout",
    "dependencies": {
      "evaluate": "all",
      "conditions": [
        {
          "option": "setting_one",
          "equals": true
        }
      ]
    },
    "settings": {
      "setting_two": {
        "label": "Label",
        "type": "boolean",
        "value": true
      },
      "setting_three": {
        "label": "Label",
        "type": "boolean",
        "value": true
      }
    }
  }
}

Display sub-groupings within groups

You may further organize settings by creating sub-groups within groups. Doing so will display sub-grouped settings underneath a sub-header that may be toggled open/closed by the publisher. Create sub-groups by wrapping settings with an additional parent enclosure, like so:

"Slideshow": {
  "icon": "slideshow",
  "settings": {
    "Playback": {
      "pulse_autostart": {
        "label": "Auto",
        "type": "boolean",
        "value": true
      }
    }
  }
}

When displayed, Playback will appear as a sub-header inside "Slideshow". The sub-group will be open in the panel by default, but you may collapse it if you'd like. Add a collapse boolean, like so:

"Slideshow": {
  "icon": "slideshow",
  "settings": {
    "Playback": {
      "collapse": true,
      "pulse_autostart": {
        "label": "Auto",
        "type": "boolean",
        "value": true
      }
    }
  }
}

Display checkbox before label

If you'd prefer to display a setting's checkbox before its label (most commonly seen with settings that use dependencies) you may add a control_first attribute set to "true", like so:

"settings": {
  "Thumbnails": {
    "icon": "img",
    "settings": {
      "show_title": {
        "label": "Show title",
        "type": "boolean",
        "value": true,
        "control_first": true
      }
    }
  }
}

Display setting on two rows instead of one

This displays labels and values on their own rows. This is most helpful when you have a <select> element with longer option labels that cause it to overflow. To split the row, add a separate_lines attribute, like so:

"settings": {
  "Layout": {
    "icon": "layout",
    "settings": {
      "index_layout": {
        "label": "Page layout",
        "type": "select",
        "value": "two_col",
        "separate_lines": true,
        "options": [
          { "label": "One column", "value": "one_col" },
          { "label": "Two columns", "value": "two_col" },
          { "label": "Three columns", "value": "three_col" }
        ]
      }
    }
  }
}

Display help note

To help explain a setting's purpose you may display a note underneath the setting in the panel. To do so you add a note member. By default the note appears centered, but you may override that with an additional note_align member assigned "left" or "right". Example:

"settings": {
  "Thumbnails": {
    "icon": "img",
    "settings": {
      "show_title": {
        "label": "Show title",
        "type": "boolean",
        "value": true,
        "control_first": true,
        "note": "This hides the site title",
        "note_align": "left"
      }
    }
  }
}

Output strings from booleans

There may be times when you need a setting that should behave like a boolean (checkbox) but should output a value that's different than true/false. For example, if you wanted to create a setting that controlled whether a title was uppercase you would first create a setting like this:

"title_uppercase": {
  "label": "Uppercase title",
  "type": "boolean",
  "values": {
    "true": "uppercase",
    "false": "none"
  },
  "value": "uppercase"
}

Then in your settings.css.lens document you'd assign the setting value to the text-transform property of an element:

h1 {
  text-transform:$title_uppercase;
}

When the user toggles the "Uppercase title" checkbox on/off in the Settings panel the h1 element in the page would change to uppercase (true) or remain normal (false).

Output rgba values for colors

If a color in your style sheet is using rgba, you can create a setting that displays both a color picker and an alpha transparency slider. This will output an rgba color value when the setting is assigned in settings.css.lens. Here's an example:

"some_rgba_color": {
  "label": "My color",
  "type": "color",
  "with_alpha": true,
  "value": "rgba(0,0,0,.3)"
}

You would then assign the setting to a color property in settings.css.lens the same way you'd assign a normal color setting:

div.thumb { background-color:$some_rgba_color; }

Assigning a scope

The theme settings panel has two views: Theme and Template. The Theme view is intended for settings that affect an entire site while Template is intended for settings that only affect the current page being viewed in the Site editor. All settings are assumed to be global and thus appear in Theme by default. To display a setting in Template you need to scope the setting to a particular template by adding a scope property. That property receives an array containing the name of the template (or templates) the setting will affect.

Here's an example. Your theme's albums index page (albums.lens) displays the title of each album. Not everyone will want titles, so you'd like to include a setting to turn them off. To do so you create a show_title boolean setting that is scoped to the albums template, like so:

"settings": {
  "Thumbnails": {
    "icon": "img",
    "settings": {
      "show_title": {
        "label": "Show title",
        "type": "boolean",
        "value": true,
        "scope": [ "albums" ]
      }
    }
  }
}

The setting now appears in Template only when the publisher is viewing the albums index in Site.

Now let's take this a step further by scoping the setting to a second template. Your theme also has an albums archive index (archive.albums.lens) that uses the same layout/markup as the albums index. You'd scope the setting to the archive template too by adding it to the same array, like so:

"settings": {
  "Thumbnails": {
    "icon": "img",
    "settings": {
      "show_title": {
        "label": "Show title",
        "type": "boolean",
        "value": true,
        "scope": [ "albums", "archive.albums" ]
      }
    }
  }
}

The show_title setting would now appear in Template when either the albums index (albums.lens) or the albums archive index (archive.albums.lens) is viewed in Site. The value of show_title would then be assigned to both templates.

Unique values for scoped settings

As explained above, a setting's value is assigned to all scoped templates. But can a setting's value be applied to one template without affecting other scoped templates? You bet. To do that you'd add a scoped_values boolean property, like so:

"settings": {
  "Thumbnails": {
    "icon": "img",
    "settings": {
      "show_title": {
        "label": "Show title",
        "type": "boolean",
        "value": true,
        "scope": [ "albums", "archive.albums" ],
        "scoped_values": true
      }
    }
  }
}

A publisher may now use a single setting to turn off titles in the albums index while leaving titles on in the albums archive index.

You could also go a step further by assigning a default value for each scoped template. To do that you'd replace value with a list of each scoped template and their default values, like so:

"settings": {
  "Thumbnails": {
    "icon": "img",
    "settings": {
      "show_title": {
        "label": "Show title",
        "type": "boolean",
        "value": {
          "albums": false,
          "archive.albums": true
        },
        "scope": [ "albums", "archive.albums" ],
        "scoped_values": true
      }
    }
  }
}

 

Note: You must include each template from scope in value or an error will occur.

 

Thus far we've demonstrated a single setting that affects multiple templates, a single setting that affects templates individually, but what about a combination of the two? A setting that affects templates individually and as a group? Can do that too. A good example for where this would be useful is with templates that share layouts or have similar purposes, like albums.lens and archive.albums.lens. Here's what that might look like:

"settings": {
  "Thumbnails": {
    "icon": "img",
    "settings": {
      "show_title": {
        "label": "Show title",
        "type": "boolean",
        "value": {
          "album": true,
          "albums,archive.albums": false,
          "favorites": true,
          "index": true
        },
        "scope": [ "album", "albums", "archive.albums", "favorites", "index" ],
        "scoped_values": true
      }
    }
  }
}	

In the example above the "Show title" setting would apply unique values to album.lens, favorites.lens and index.lens. albums.lens and archive.albums.lens would be assigned a shared false value, which if edited would affect both templates.

Out-of-scope settings

So what happens if a setting is used in a template not assigned to scope? That template would receive a false value automatically. To change that return value to true you'd assign an out_of_scope_value property, like so:

"settings": {
  "Thumbnails": {
    "icon": "img",
    "settings": {
      "show_title": {
        "label": "Show title",
        "type": "boolean",
        "value": true,
        "scope": [ "albums", "archive.albums" ],
        "out_of_scope_value": true
      }
    }
  }
}

Assign scope to an entire group

If you have an entire group of settings that share the same scope you may optimize your code by assigning a single scope to the parent group instead. The scope would then be used for every setting the group contains. For example:

"settings": {
  "Thumbnails": {
    "icon": "img",
    "scope": [ "albums", "archive.albums" ],
    "settings": {
      "show_title": {
        "label": "Show title",
        "type": "boolean",
        "value": true
      },
      "show_description": {
        "label": "Show description",
        "type": "boolean",
        "value": true
      }
    }
  }
}

If a setting inside the group has its own scope setting, that scope will take precedence.

Reload theme preview

Most settings are able to update the live preview of a theme without a page reload, but you may at some point need a way to force-reload the preview to make magic happen. You can do this by adding a reload_preview boolean set to true, like so:

"settings": {
  "Layout": {
    "icon": "layout",
    "settings": {
      "page_layout": {
        "label": "Layout",
        "type": "select",
        "options": [
          { "label": "List", "value": "list" },
          { "label": "Grid", "value": "grid" }
        ],
        "value": "grid",
        "reload_preview": true
      }
    }
  }
}
support@koken.me
http://assets3.desk.com/
false
koken
Loading
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
about
false
Invalid characters found
/customer/en/portal/articles/autocomplete