Configuration of Theme options

Overview

Every template/theme/style can provide a file called "config.inc.php" which can hold specific commands to execute before a template is loaded; there you could register custom PHP/Smarty functions in the past.

Custom Options

Since Serendipity 1.1-alph4, you can also enter a special configuration array into this file, which will then allow the Serendipity user to configure theme-specific options like background-colors etc.

This array must have a format like this:

<?php
$template_config = array(
    array(
        'var'           => 'colorset',
        'name'          => 'Color Set',
        'description'   => 'Enter the color set you want to use for this site',
        'type'          => 'select',
        'default'       => 'green',
        'select_values' => array('green' => 'Green', 'blue' => 'Blue', 'black' => 'Black')
    ),
    
    array(
        'var'           => 'banner_image',
        'name'          => 'Banner Image',
        'description'   => 'Enter the URL to your banner image',
        'type'          => 'string',
        'default'       => '/serendipity/your_banner.jpg'
    ),

    array(
        'var'     => 'sidebars',
        'name'    => 'Sidebars',
        'type'    => 'string',
        'default' => 'left,hide,right'
    )
);

$template_config explained

It doesn't matter where inside the config.inc.php file you set these options. You can use any amount of configuration options - append them like above, by copy+pasting the array(...) block below each other. Pay attention that your array(...) construct is valid PHP code. You need to enclose everything with single or double quotes, and not miss a comma.

The "var" array index holds the config option name, which you later will query within your Smarty template.

The "title" array index defines the title of the configuration option, "description" holds a detailed option.

The "type" array index specifies, how your option shall be shown to the user. Values can be: select, tristate, boolean, radio, string, html, hidden.

If you use the "select" type, you need to specify an array of options like in the first example for the "select_values" array index.

The "default" array index holds the default value for your template option, if the user did not (yet) choose any of his own values.

Special attributes

The var sidebars is a very special configuration option. Its comma-separated list of column names indicates which and how many sidebars a template supports.

The plugin manager interface will show one column for each of the configured sidebars, so that people can move around plugins from one to the other location.

Note that no spaces are allowed in sidebar names, and no sidebar name may be longer than 6 characters.

If you do not want to make the sidebar names configurable by the users, you can also set $template_config['sidebars'] = 'left,right,hide' in your template's config.inc.php file.

Internationalization!

Please try to let your config.inc.php include a language file, so that you can use constants as a description:

<?php
// Probe for a language include with constants. Still include 
// defines later on, if some constants were missing
$probelang = dirname(__FILE__) . '/' . $serendipity['charset'] 
     . 'lang_' . $serendipity['lang'] . '.inc.php';
if (file_exists($probelang)) {
    include $probelang;
}

include dirname(__FILE__) . '/lang_en.inc.php';

$template_config = array(
    array(
        'var'           => 'colorset',
        'name'          => MYTEMPLATE_COLORSET_TITLE,
        'description'   => MYTEMPLATE_COLORSET_DESCRIPTION,
        'type'          => 'select',
        'default'       => 'green',
        'select_values' => array('green' => MYTEMPLATE_COLORSET_GREEN, 
                                 'blue' => MYTEMPLATE_COLORSET_BLUE)
    ),
);

Using constants makes it easily possible for other users to translate your template options names into other languages. Once you have defined it like this, you can create files like "lang_en.inc.php" and "lang_de.inc.php" with contents like these:

define('MYTEMPLATE_COLORSET_TITLE', 'Color Set');
define('MYTEMPLATE_COLORSET_DESCRIPTION', 'Enter the color set you 
want to use for this site');

Now you have specified your options. Once you select your template from the Serendpity Admin Interface, you will see those options presented to you on the interface.

The Smarty way

You must of course also make your Template use the options you specified. They are available as {$template_option.XXX} smarty variable within any of your Smarty template files. This means you could do something like this inside your index.tpl file:

{if $template_option.colorset == 'green'}

<link rel="stylesheet" href="templates/mytemplate/colorset/green.css" />

{elseif $template_option.colorset == 'black'}

<link rel="stylesheet" href="templates/mytemplate/colorset/black.css" />

{elseif $template_option.colorset == 'blue'}

<link rel="stylesheet" href="templates/mytemplate/colorset/blue.css" />

{/if}