Theme Settings

This plugin is targeted to theme developers. It makes it easy for you to provide theme settings to allow your users to customize the theme without editing CSS files.

In order to easily change CSS styles, you should use LESS or SCSS to define your styles. An easy integration with LESS or SCSS can be achieved with  my LESS and SCSS plugins.

Installation

Download the plugin from http://get-simple.info/extend/plugin/theme-settings/840/, unzip it and copy it to the plugins directory of your GetSimple installation.

Usage

In this tutorial we will show how to adapt a theme so that it has two configurable options for the GetSimple user:

• a color schema to globally change colors in the CSS
• a tag line that is displayed below the title in the site header

This example assumes that you are using LESS for your CSS styles.

• First copy your CSS file to a LESS file, e.g. default.css to default.less.
• Replace all colors that should be configurable with variables in default.less, e.g.

html {
  color: @textColor;
  ...
}
#header {
  background-color: @backgroundColor;
  ...
}
...

• Change your template (e.g. your default template template.php) to include the LESS file and read the tag line from the theme settings (we make sure that it will work even if the Theme Settings plugin or the LESS plugin are not installed):

...
  <?php if (function_exists('get_less_css') && function_exists('return_theme_settings')) { ?>
    <link rel="stylesheet" type="text/css" href="<?php get_less_css('default.less', return_theme_settings()); ?>" />
  <?php } else { ?>
    <link rel="stylesheet" type="text/css" href="<?php get_theme_url(); ?>/default.css" />
  <?php } ?>
...
  <div>
    <?php if (function_exists('get_theme_setting')) get_theme_setting('tagline', ''); ?>
  </div>
...

• In your theme directory create at least one schema file named default.properties and any number of additional *.properties files to define additional color schemes. E.g. here is default.properties:

textColor=DarkRed
backgroundColor=Crimson

• In your theme directory create a settings.php file to specify the configuration HTML:

<?php
if(!defined('IN_GS') || !cookie_check()) die;
?>
<div class="leftsec">
  <p>
    <label for="schema">Color Schema:</label>
    <?php get_schema_select(); ?>
  </p>
</div>
<div class="rightsec">
  <p>
    <label for="tagline">Tag Line:</label>
    <input type="text" class="text" name="tagline" id="tagline" value="<?php get_theme_setting('tagline'); ?>">
  </p>
</div>

You are done!

If your theme is activated in the GetSimple administration, the user will see an additional side menu item under the Themes tab - Configure Theme. There he can select a color scheme and enter a tag line.

API

The plugin provides the following functions for your template files, if the themes directory contains a file settings.php:

• function return_theme_settings($defaults)
  Returns an array with the current theme settings. Default values can be provided by the $defaults parameter. It can be an array with the default properties or a string for a schema, e.g. 'default' for the schema file default.properties.
• function return_theme_setting($name, $default=null)
  returns the value of theme setting $name or the $default value.
• function get_theme_setting($name, $default='', $isHtml=false)
  outputs the value of theme setting $name or the $default value. Special character like <, >, & are replaced with HTML entities unless $isHtml is true.

Within your settings.php you can use the following function:

• get_schema_select($default=null)
  outputs the schema drop down, selecting the currently selected schema, or the $default schema, if no settings are saved.

The settings of a theme are saved in a file theme_settings_themename.xml in the data/other directory.