Search
Table of ContentsDeveloper's Manual
Editors for the Yana Framework Index General introduction

## 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 ammount 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.

    <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 containt 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.MEIN_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.

### 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 adress 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 | path of the script, incl. 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: [%$ATIME|date%]
MTIME | string | yes | n/a | File property | Inserts at this place the date, when the HTML-template was last changed: [%$MTIME|date%]
CTIME | string | yes | n/a | File property | Inserts at this place the date, when the HTML-template was created: [%$CTIME|date%]
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.
PROFILE.BGCOLOR, PROFILE.BGIMAGE | String | no | n/a | Profile file | Background color and image of the web site
PROFILE.PFONT, PROFILE.PSIZE, PROFILE.PCOLOR | String | no | n/a | Profile file | font familiy, size, color of paragraphs (P-tags)
PROFILE.HFONT, PROFILE.HSIZE, PROFILE.HCOLOR | String | no | n/a | Profile file | font familiy, 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://...)

Editors for the Yana Framework Index General introduction

Thomas Meyer, www.yanaframework.net