Templates

How the templates work

We have tried to make the templates as customisable as possible. Through a simple set of files and a set of replacement variables you can intergrate DWmail into your own site design.

There are three types of template:

Below is a representation of main mail box using template 'silver'.

Template

As you can see in this example the global template is the header. The page template is the mail box listings and the sub template is the left hand menu. There are actually three displayed on this page but for demonstration purposes we have only highlighted one.

Creating or customising your template

Supplied with DWmail are three templates

The Dominion Web site contains additional templates developed and available for download to customers for free.

How to install a new template in DWmail

The templates directory contains a sub-directory for each template set. To create your own template we recommend copying a default template which matches your final design closest and give it a new name e.g. 'mytemplate'. From here you can customise your template whilst referring to the original version.

For the official templates available for download, simply unzip these files into the templates directory and then upload your new template directory to your DWmail installation. Once all of the files have been uploaded you'll now need to tell DWmail that this template is available for user selection.

Login to the administration section by pointing your web browser to the admin sub directory. Click on template options.

 

Select the template directory you have just uploaded, in the box the the right enter the name of the template, then click on the + icon to install it.

Alternatively if the templates directory has writable permissions you can use the 'Install a new template' upload facility.

Click on the browse... button and select a .zip template file and press Upload File. Once this has been uploaded follow the proceedure above to add this template to the list of available templates.

How to change the title of a template or which ones are available

Login to the administration section by pointing your web browser to the admin sub directory. Click on template options.

You will be presented with a list of currently available templates. If you wish to edit the title of one of these existing templates then simply edit the title and click on the save icon (the blue disk). If you wish to remove this template from the available templates list then click on the red cross icon.

Note deleting a template from the available list will not physically delete the template directory, it just removes it from the drop down list of available templates

Changing the Default Template and Character Set

Login to the administration section by pointing your web browser to the admin sub directory. Click on template options.

To change the default template select the drop down list of available templates and click on Update Template Settings.

To change the default language file select the drop down list of available templates and click on Update Template Settings.

Variables in templates

DWmail's templates use a custom variable system. All variables are contained with in square brackets. For example [session] in a template file would automatically be replaced with the session id for the user. Each template file supports different variables, details of which are available below. Some templates also support conditional variable tags. For example if a template had the following text:

<p>Paragraph 1</p>
[ifimap]<p>Paragraph 2</p>[/ifimap]
<p>Paragraph 3

then if the user has logged into DWmail using the IMAP4 protocol then the template would display:

Paragraph 1

Paragraph 2

Paragraph 3

However if the user has logged in using the POP3 protocol then the template would display:

Paragraph 1

Paragraph 3

The variable [CurrentTemplate] can be used in any template file to output the current template name e.g. if you wanted to include an image that is common to all templates directories you can use <img src="templates/[CurrentTemplates]/images/image.gif" />

Session variables

Session support in PHP consists of a way to preserve certain data across subsequent accesses. A visitor accessing DWmail on your server is assigned an unique id, the so-called session id. The content of which is stored server-side. This means that we can store the users login details server-side for accessing subsequent pages after logging in, thus minimising and security risks.

A session variable is required throughout the DWmail templates where-ever a URL, redirect or a form is displayed. The session variable tags using throughout the DWmail templates work out if your PHP version automatically adds session variables and if not displays it manually.

There are four main types that are used across DWmail

Multi-language capabilities

The DWmail templates are language independent. All of the text displayed to the screen is done so through the use of language packs. At this time DWmail only ships with an English language packs but you can create your own to use and allow the user to select between.

Creating your own language packs

  1. To create your own language file for DWmail, create a directory within the lang directory, it should be using the ISO 639-1 language code for your desired language. E.g. for English the ISO code is 'en'
  2. Take a copy of the files in the en directory as your base template and put them in your new language directory.
  3. Edit the variables and arrays in each of the files to your language
  4. Do not change the array keys for the variables but feel free to change the values to your language.
  5. Then from the admin are, click on Language Options.
  6. Go to the bottom of the Available Languages area to the area with the blank fields.
  7. Select from the drop down the directory ISO language code you just uploaded
  8. Enter the character set for that language e.g. for en we use iso-8859-1
  9. Enter a description e.g. English
  10. If you have an aspell dictionary installed for this language then you can enable the spell check for it
  11. Enter the character set for aspell. ASpell sometimes defines this in a slightly different format to the one we used above, hence why it's requested twice e.g. for en it is iso8859-1
  12. Enter the PHP locale for this language e.g. en_US
  13. Enter whether the text flow for this language is left to right or right to left
  14. Click on the green + icon to install this new language pack.
  15. Please make sure that ALL text entered is in ASCII characters or using HTML entities for descriptions
  16. Important Note: DWmail has NOT been tested with multibyte charactersets e.g. JIS, SJIS. Single byte character sets such as ISO-8859-*, EUC-JP, UTF-8, etc should all work fine within DWmail

Official Language packs

If you wish to consider your own language set to be added to the shipped version of DWmail your langage file must be an accurate translation of the standard English character set and must be a word for word translation (accepting, of course, changes in the structure between languages).

Please submit a support ticket with details on your language extension.

We will of course add credit in the language files you create with your selection of your name and/or your email address and/or your website address

Please note we may not accept all submissions as official language sets

The boiler plate copyright notice header text for your own language pack can be found in the lang directory and is called TEMPLATEHEADER.txt and goes at the top of each language PHP file. See the English language headers to see what to put where.

Language Template Variables

Throughout the templates you will see a number of template variables of the form [lang=VariableName]. All language files take this format and each file makes use of a specific language file.

For example composemessage.tpl's language variables are all contained in the language file compose.inc.php and in the array $lang['SCompose'].

To make things easier DWmail will loop the entire array key $lang['SCompose'] in that template and replace any language variables it finds. This has the great advantage that you can add new language variables very easily without editing the main PHP files, only the language include file and the template file itself. For example, if you wanted to add a new sentence to composemessage.tpl you could add [lang=NewSentence] to the template file and then simply create $lang['SCompose']['NewSentence'] = 'Your new sentence here'; in compose.inc.php

For this reason the [lang] variables are not given in the template file details given in the section below.

Editing templates

The following is a list of possible templates available through DWmail. the 'silver' template makes use of most of these and 'pda' does not.

Click on a file name to view details about what each template is, how it works and what variables you can use in that template. Template can be edited in two different ways.

Firstly you can do so through any text editor, such as notepad, save and re-upload the file to the server, alternatively if the template directory and the .tpl files themselves have writable permissions then you can login to the administration area, click on Edit Templates, select the template directory you wish to edit, then select the template itself.

This list is currently out of date and is being refreshed

Standard Templates

Frameset specific templates

Some template use preview panes and framesets, these are templates specific to those types