Step-by-step instructions

1. In the home directory of your application, you will find a directory with the name "skins/", in this directory you will find all the currently installed skins.
2. To add a new skin theme, first copy the contents of the directory "default/" including its subdirectories to a new directory with the name of your skin. For example, "skins/mytheme/".
3. Open the file "index.html" in a web editor of your choice. You can also use Notepad or, under Unix / Linux, Emacs.
4. Adjust the file as you see fit, and save your changes.
5. Finally, you must create a configuration file for your skin. This file contains the names of your skin and a description of the author. You can use the file "skins/default.config" as a sample. Copy this file to another name. For example, "skins/mytheme.config".
6. This skin file can by edited in any text editor. Open the file, modify the data as required. Make sure that the file paths are correct. Then save your changes.

Configuration of Skins

Here is a simple example.

<SKIN_INFO>
    <NAME>my theme</NAME>
    <DESCRIPTION>description of my theme</DESCRIPTION>
    <AUTHOR>my name</AUTHOR>
    <CONTACT>my web site</CONTACT>
    <LOGO>%SKINDIR%mytheme/data/preview.gif</LOGO>
    <DIRECTORY>mytheme/</DIRECTORY>
</SKIN_INFO>

The syntax is largely self-explanatory. The fields "Name", "Description", "Author" and "Contact" are free text fields. For the "name" you can have any name, which describes your theme. The same applies to the field "Description". Make sure that the only allowed whitespace characters are simple spaces. You can add a line break, if necessary, by writing the text "[br]". The field "Author" should be your name and "Contact" usefully an e-mail or Internet address, where the user may view your web site or download updates.

The field "Logo" is a preview image. The place holder %SKINDIR% refers to the directory in which the skins are saved and should always be used. The graphic should preferably be in GIF, PNG or JPEG format, and about 300x300 pixels in size.

The "Directory" must always be specified. It names the directory in which you theme is stored.

Configuration of templates

Here is a simple example.

<MY_TEMPLATE>
    <FILE>template.html</FILE>
    <STYLE>
        <0>style/default.css</0>
        <1>foo1/foo2.css</1>
        <MY_CSS>foo3/foo4.css</MY_CSS>
    </STYLE>
    <SCRIPT>
        <0>foo5/foo6.js</0>
        <MY_SCRIPT>foo7/foo8.js</MY_SCRIPT>
    </SCRIPT>
    <LANGUAGE>
        <0>guestbook</0>
        <1>admin</1>
    </LANGUAGE>
</MY_TEMPLATE>

Note that "MY_TEMPLATE" acts as an identifier, which identifies the template. You can use this Id in the configuration files for your plug-ins to refer to the template. The text can be chosen arbitrarily. However, be careful that the Id contains no special characters or spaces, it must begin with a letter and must by unique throughout the entire application. The Id is not case-sensitive.

There are 4 fields: "File", "Style", "Script" and "Language". The field "File" names the file name. The other fields are optional and serve automation.

The field "Language" contains references to one or more files, which provide text strings in various languages for this template. For example, the value "guestbook" refers to the file "languages/XX/guestbook.config", where the text "XX" is automatically replaced by the system with the name of the user's language of choice. E.g. "de" for German or "en" for English.

The field "Style" can contain multiple references to stylesheets. Similarly, the field "script" contains links to one or more JavaScript files. These files are automatically included when the template is called.

Notice: If in a skin a required template is not defined, or properties of this template ( "Styles", "script", "Languages") are not declared, the program automatically falls back to the "Default"-skin settings.

This is done as follows.

1. If in the current skin a template is undefined, take over the default settings for the missing template completely.
2. If the template exists, but a property, e.g. "Style" is undefined, then it is taken from the "Style"-definition of this template in the default-skin settings. For "Language" and "Script" this is done in the same way.
3. If the template exists and the property is defined, then the defined properties are merged with those of the default-skin.
   The program does this as follows:
   • All numeric entries are always appended. For example: the entries STYLE.0, STYLE.1 aso. of the default skin are taken, nexte all entries STYLE.0, STYLE.1, STYLE.2 aso. from the current skin are appended to this list.
   • Named entries, for example STYLE.MY_CSS in the default-skin, are overwritten by entries of the same name in the current skin.

This behavior may seem illogical at first, but has a quite a deeper meaning. It allows to exchange individual style sheets, or scripts in a newly created skin. At the same time it also allows individual style sheets, or scripts to be excluded from this mechanism. Both variants are frequently used and have their own application areas.

Another example to illustrate this behavior. For the Template "MY_TEMPLATE", the following definition exchanges only the CSS file "MY_CSS" defined int the default skin with another file. All other settings remain unchanged.

<MY_TEMPLATE>
    <STYLE>
        <MY_CSS>foo/bar.css</MY_CSS>
    </STYLE>
</MY_TEMPLATE>

As you can see in this example, no new HTML template is defined, but the setting of the default skin is used. This means that there is no need for the HTML template from the default-skin to be copied to the new skin, or even edited, to change the layout. This avoids unnecessary redundancy and makes it easier for you to maintain your HTML code.

* "required" means in this case "unequal NULL"