>> Table of Contents >> Developer's Manual

Creating templates and skins

Editing HTML-templates

This program uses so called "templates". What ever you change on these pages will also change the look and feel of your application. These files are stored in the "skins" directory. You can open and edit these files like any normal HTML page in your web editor. For changing the files no knowledge in HTML is necessary, however: it will come in quite handy, if you plan on implementing a larger amount of changes.

In any case you should make copies of the original files, before you apply any changes.

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.

Tutorials on creating your own templates can be found on the at Smarty's web site:http://smarty.net

Configure templates and skins

If you are not just editing an existing template, but want to create a new one - or perhaps even a new skin -, then it is not enough to just edit template files. You must also understand and be able to apply the configuration of templates and skins.

However, this is very easy and limited to two configuration files. One for your new templates and the other for the skin.

Configuration of Skins

Here is a simple example.

    <NAME>my theme</NAME>
    <DESCRIPTION>description of my theme</DESCRIPTION>
    <AUTHOR>my name</AUTHOR>
    <CONTACT>my web site</CONTACT>

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.


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.


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.

List of permitted principal wildcards

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

Wildcard Type Required * Default value Origin Description
PHP_SELF String yes n/a PHP Name of the executed script file
REMOTE_ADDR String yes n/a PHP IP address of client.
SETTINGS.WEBSITE_URL String no n/a calling URL complete URL of the script (incl. http://...)
REQUEST_URI String no n/a calling URL called path of the script, including parameters (/yana/index.php?...)
QUERY_STRING String no n/a calling URL list of parameters passed to the script
ID String yes default GET/POST ID-Code of the current profile.
ACTION String no <empty> GET/POST Name of the currently (to be) executed action.
TARGET String no <empty> GET/POST Target of the currently executed action. (e.g. the ID of a data set)
SESSION_NAME, SESSION_ID String no <empty> GET/POST Name and ID-Code of the current session (should be added to all hyperlinks)
PAGE integer no 0 GET/POST The number of the data set from which the show started. (If required)
ATIME string yes n/a File property Insert date and time when the HTML-template was last accessed at this place:
MTIME string yes n/a File property Inserts at this place the date, when the HTML-template was last changed:
CTIME string yes n/a File property Inserts at this place the date, when the HTML-template was created:
LANGUAGE Array yes n/a Language file(s) List of all text strings defined in the currently selected translation.
PROFILE Array yes n/a Profile file List of all settings in the currently used profile.
The following are some examples. Note that all fields mentioned here may also contain a NULL value.
String no n/a Profile file Background color and image of the web site
String no n/a Profile file font family, size, color of paragraphs (P-tags)
String no n/a Profile file font family, size, color of headings (H1-,H2-,H3-tags)
SKIN_INFO Array no n/a Skin file Informations on the selected Skin
LANGUAGE_INFO Array no n/a Language file Informations on the selected language
LANGUAGE Array no n/a Language file(s) Translations (texts)
SETTINGS.WEBSITE_URL String no n/a Language file(s) complete URL of the script (incl. http://...)

Author: Thomas Meyer, www.yanaframework.net