@Mail System Documentation : v 3.4
The latest version of this file can be found at:
http://atmail.nl/docs/

How to Modify the Interface of @Mail

This document explains how to modify the interface of the @Mail application. Learn how the template system works, how variables are embedded and parsed through HTML templates.

  1. How the template system works
  2. The $atmail template variable
  3. The $var template variable
  4. How variable are parsed to the HTML templates
  5. How to parse your own variable
  6. Adding a new language template
  7. Listing of Global variable names
  8. Common HTML templates and how to modify
    1. signup.html
    2. login.html
    3. readmail.html
    4. composetext.html
    5. composehtml.html
    6. addressbook.html
    7. settings.html
    8. showmail.html
    9. folders.html
  9. Style Sheet information
  10. Editing the Simple Interface
  11. Related Technical / Support Information

1. How the template system works

The user interface of @Mail is based on HTML templates. Allowing you to easily re-brand the interface into your company's/websites theme. No experience in programming is required to modify the look of the user interface.

Customization of the interface is easy. Using a HTML or Text editor you can modify the template files used by @Mail. By modifying the templates you can add your own HTML tags or modifying the existing layout. The templates are interpreted by @Mail on the fly, variables embedded in the templates are expanded into values depending on the users session.

@Mail parses a different template depending on the user request. Each function in @Mail has its own unique template. The user has the choice to select which interface to use , and the language type. Each language interface in @Mail has the entire HTML template directory translated.

To illustrate how the template system works. When a user clicks to compose an eMail message the compose.html file is parsed, embedded variables in the file are expanded into the users values.

An example request in @Mail

  • User clicks to compose an eMail message

  • @Mail parses the composetext.html or composehtml.html file depending on the users eMail settings (if using HTML or plain editor)

  • @Mail opens the html/composetext.html file and reads the file line by line, all strings that contain a $ sign are evaluated and expanded into their variable values.
 Snippet of HTML:
   
   <th align="right" width=14% NOWRAP bgcolor="$atmail->{PrimaryColor}">    
   <div class="sw">From:&nbsp;</div>
   </th><td bgcolor="$atmail->{SecondaryColor}" NOWRAP width="50%">    
   <div class="SW">&nbsp; 
   <select name="emailfrom" class="stdsel">
   <option value="$atmail->{username}@$atmail->{pop3host}">
   $atmail->{username}@$atmail->{pop3host}</option>
   </select>
You can make your own LoginStyle, using the existing templates as examples

root# cp -r html/english/ html/template_name/

This will create a new template design directory with the simple interface as the template. You could also use the Professional (html/blue_pane) interface as the template is you wished.

To add your new interface to the Signup page

In html/login.html add in the <select name="LoginType"> and extra option

<option value="template_name">My Custom Interface</option>

Change "My Custom Interface" to the Name of the Interface and "template_name" to the name of the directory containing the template files. You can add / remove and modify any of the design, but be careful maintaining the special $var variables since these are required for the interface to function.

With the Template system used by @Mail, you can add your own banner-ads , company theme's / layout , logo's , extra links, etc. to the @Mail Webemail System.

2. The $atmail template variable

There are 2 types of variables used by @Mail. The first variable begins with $atmail , these are used to retrieve user preferences and settings. Anywhere in a HTML template you can reference the $atmail->{type} variable to print/display user information.

Examples used in the compose template

  • $atmail->{username}
    The users login name

  • $atmail->{pop3host}
    The users mail hostname

  • $atmail->{PrimaryColor}
    The primary color reference used by @Mail templates . See the table for a complete listing

  • $atmail->{SecondaryColor}
    The users secondary color preference. All the screens in @Mail reference the color layout from the users settings, allowing the same HTML template to use multiple color themes.

3. The $var template variable

The second type of variables used by @Mail begin with a $var . These are variables created within @Mail that are parsed into the HTML template. The variables are represented as a Hash data type in Perl.

For example, when reading an eMail message @Mail fetches the message headers/body and stores the values into the $var hash. The $var contains different values depending on the function the user requested. When reading an eMail message the $var{EmailSubject}, $var{EmailFrom}, $var{EmailTo}, etc variables are created in @Mail and referenced by the HTML template.

When a user requests to read a message, the readmail.html file is parsed. This template contains references to the $var hash which expands to the messages subject, from, to, and other mail fields.

Snippet of HTML:

   <th><div class="SW">Subject:&nbsp;</div></th>
   <td bgcolor="#fafafa" width="64%">
   <div class="SW">&nbsp;$var{EmailSubject}</div>
   </td><td bgcolor="#fafafa" valign="center">
   <div align="right"><font class="SW"><b>
   <a href="compose.pl?id=$var{id}&folder=$var{folder}&func=reply">
   Reply</a>
@Mail parses the template and expands the $var variables into values. The requested URL to read a message contains the message ID and folder to read the message from. A description of the variables used:
  • $var{EmailSubject}
    Contains the messages subject

  • $var{id}
    The messages unique ID number

  • $var{folder}
    The current folder the user is using . E.g. reading message 5 ($var{id}) from Inbox ($var{folder})

4. How variables are passed to HTML templates

Every user request is handled by a @Mail Perl script. Since @Mail include the source-code you can edit any of the scripts and modify their behavior. When a function loads variables are created within the Perl script which are parsed by the HTML template and sent to the users browser.

Input is received via the URL . Depending on the arguments passed the actions of the script will differ. As an example, when a user click an eMail message the browser is sent to:

 http://yourdomain.com/atmail/reademail.pl?folder=Inbox&id=20

This will run the reademail.pl script loading message number 20 from the folder Inbox. The reademail.pl script loads the value of the arguments using the functions below 

   # Which EMail to read
   $var{id} = $atmail->param('id');
   $var{folder} = $atmail->param('folder');

Each function in @Mail has it's own .pl file. Each file loads different variables from the URL depending the function and user input.

At the end of each script the result is printed to the browser. Using HTML templates variables created in the script are parsed and are displayed accordingly. For the reademail.pl function

 print $atmail->parse("$atmail->{UserLanguage}/html/readmail.html",
   id => $var{id},
   folder => $var{folder},
   EmailSubject => $EMail>{subject},
   EmailTo => $EMail>{to},
   EmailCc => $EMail>{cc},
   EmailFrom => $EMail>{emailfrom},
   EmailHtml => $EMail>{html},
   EmailTxt => $EMail>{txt},
   EmailDate => $EMail>{date},
   EmailType => $EMail>{type},
   EmailPriority => $EMail>{priority},
   atmailstyle => $var{atmailstyle},
   Attachments => $var{attachments}
   );

The first argument is the filename to parse, for this function English/html/readmail.html . The $atmail->{UserLanguage} variable is dependent on the users settings. The second argument is a list of variables to display in the template. The left side is the name of the variable and it's value followed by the => sign. The id, folder names are referenced from the URL while the rest are the messages headers/body.

Alternatively you can skip defining which variables to import into the HTML template by the following

 print $atmail->parse("$atmail->{UserLanguage}/html/readmail.html",
   EmailSubject => $EMail>{subject},
   EmailTo => $EMail>{to},
   EmailCc => $EMail>{cc},
   EmailFrom => $EMail>{emailfrom},
   EmailHtml => $EMail>{html},
   EmailTxt => $EMail>{txt},
   EmailDate => $EMail>{date},
   EmailType => $EMail>{type},
   EmailPriority => $EMail>{priority},
   %var
   );

Where %var is the entire hash element that contains all the variable names. Some functions may have unnecessary variables to import that's why you can define them by hand. In this example the EMail message/headers are not contained in the $var element hence the reason to define them.

5. How to parse your own variables

You can define your own variables by passing them in the URL to the script . You can also create new variables anywhere in the @Mail scripts.

As an example we pass an extra variable in the URL below

 http://yourdomain.com/atmail/reademail.pl?folder=Inbox&id=20&text=hello
 $var{text} = $atmail->param('text')

This variable will now be accessible within the script and to the HTML template. In the reademail.pl script we can use the variable passed from the URL and display in the HTML template.

By modifying the html/readmail.html template we can display the new variable

<html>
<head>
<title>$var{text} reading message $var{id} from $var{folder}</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head>
....

Once a user clicks to read a message, the title will appear 'hello reading message 20 from Inbox'

6. Adding a new language template

@Mail supports operation in multiple languages. Please see The Translation Guide

7. Global Variable names used by @Mail HTML templates

Variable Name Description Type
$atmail->{Account} The users account name. e.g. test@domain.com Text
$atmail->{Advanced} Set message popup boxes Boolen
$atmail->{AutoReply} Account autoreply text Text
$atmail->{BgColor} Users selected bgcolor Color
$atmail->{EmailHeaders} What EMail-headers to display Text
$atmail->{EmptyTrash} Empty the users Trash folder on logoff Boolen
$atmail->{FontStyle} The selected font to style the interface Text
$atmail->{Forward} Forward EMail to another account Text
$atmail->{HeadColor} Head Color Color
$atmail->{HeaderColor} Header Color Color
$atmail->{HtmlEditor} Use plain or advanced editor Boolen
$atmail->{LeaveMsgs} Leave msgs on remote POP3/IMAP server Boolen
$atmail->{LinkColor} Link color Color
$atmail->{LoginType} The selected interface to use Text
$atmail->{MailType} Users mailbox type. SQL/POP3/Flat/IMAP Text
$atmail->{MboxOrder} Order to sort eMails Text
$atmail->{Mode} User mailbox mode. SQL or flat-file Text
$atmail->{MsgNum} Number of messages to display Num
$atmail->{NewWindow} Open messages in new window Boolen
$atmail->{PrimaryColor} Primary interface color Color
$atmail->{RealName} Users fullname Text
$atmail->{Refresh} Time set to refresh mailbox window Num
$atmail->{ReplyTo} Users ReplyTo address Text
$atmail->{SecondaryColor} Secondary Interface color Color
$atmail->{Signature} Users signature Text
$atmail->{TextColor} Text Interface color Color
$atmail->{ThirdColor} Third Interface color Color
$atmail->{TimeZone} Users selected TimeZone Text
$atmail->{UserLanguage} Users selected Language Text
$atmail->{UserQuota} Size of user quota Num
$atmail->{VlinkColor} Visited Link color Color

8. Common HTML templates and Tags

signup.html

<INPUT name="username" size="9"
<INPUT name=password
<INPUT name=password2
<INPUT name="PasswordQuestion"
<INPUT name=OtherEmail>
<INPUT name="FirstName"
<INPUT name=LastName
<INPUT name="BirthYear" size=6 value="19"
<INPUT name="Address"
<INPUT name=City
<INPUT name="Postcode" size=5
<INPUT name="NewAccount" type="submit" value="Create Account &gt;&gt;">

login.html

HTML Tag Description

<input type="submit" name="Login" value="Login">

 Login Button

<input name="username" size="9" value="$var{username}">

Username for Account
<input name="password" type="password"> Password for Account

<select name="pop3host">$var{domainbox}</select>

Select box containing a list of hostnames
<select name="LoginType">
<option value="blue_pane" selected>Professional (IE5+ NS6+)</opt
<option value="simple">Simple (Any browser)</option>
<option value="1pane">1 Pane</option>
</select> 		The interface type the user

readmail.html

HTML Tag Description
<input type=hidden name="func" value="open">  
<input type=hidden name="add" value="1">  
<input type="submit" name="add" value="Add Abook"> Add the sender to the address book
<input type=hidden name="EMail" value="$var{EmailFrom}"> The addres of the sender

<select name="useremail" >
<option value="$var{emailfrom}">$var{EmailFrom}</option>
</select>

 The addres of the sender
<select name="to" >
$var{EmailTo}
</select>		 Who the message is addressed to

composetext.html

HTML Tag Description
<input type="hidden" name="contype" value="text/plain">  
<input type="hidden" name="UIDL" value="$var{UIDL}">  
<input type="hidden" name="unique" value="$var{unique}">  
<input type="hidden" name="type" value="$var{type}">  
<input type="hidden" name="DelDraft" value="$DelDraft">  
<input type="text" name="emailto" size="49" value="$var{To}"> Who the is addressed To
<input type="text" name="emailcc" size="49" value="$var{Cc}"> Addess to CC the message
<input type="text" name="emailbcc" size="29" value="$var{Bcc}"> Address to Bcc the message
<input type="text" name="emailsubject" size="49" value="$var{Subject}"> The messgae Subject
<input type="button" name="Submit32" value="Add Recpients" onclick="AddRecpients()"> Add person to send to
<input type="submit" name="Send" value="Send"> Send the message
<input type="reset" name="Submit22" value="Clear"> Clear the message box
<input type="button" name="AddRec" value="Add Recpients" onclick="AddRecpients()">  
<input type="button" name="SpellBtn" value="Spell Check" onClick="SpellCheck()"> Spell check the message
<input type="button" name="Attach" value="Attachment" onclick="Attachment()"> Add an attachment
<input type="submit" name="Draft" value="Save Msg"> Save as Draft
<input type="submit" name="Send" value="Send"> Send the message
<input type="hidden" name="emailmessage" value=""> The Message body
<input type="hidden" name="emailto" value=""> Address the eMail is to
<input type="hidden" name="emailcc" value=""> Address to CC message
<input type="hidden" name="emailbcc" value=""> Address to Bcc the message
<input type="hidden" name="emailsubject" value=""> The subject of the message
<input type="hidden" name="HtmlEditor" value=""> To use the HTML editor
<select name="emailfrom" >
<option value="$atmail->{username}@$atmail->{pop3host}">
$atmail->{username}@$atmail->{pop3host}
</option></select>		 Address to send the eMail from
<select name="emailpriority" >
<option value="0">Normal</option>
<option value="5">Low</option>
<option value="1">High</option>
</select>		 The Priority of the message
<textarea name="emailmessage" cols="81" rows="20">$var{Msg}
$var{Signature}
</textarea>		 The eMail Message and signature

composehtml.html

HTML Tag Description
<input type="hidden" name="contype" value="text/plain">  
<input type="hidden" name="UIDL" value="$var{UIDL}">  
<input type="hidden" name="unique" value="$var{unique}">  
<input type="hidden" name="type" value="$var{type}">  
<input type="hidden" name="DelDraft" value="$DelDraft">  
<input type="text" name="emailto" size="49" value="$var{To}"> Who the is addressed To
<input type="text" name="emailcc" size="49" value="$var{Cc}"> Addess to CC the message
<input type="text" name="emailbcc" size="29" value="$var{Bcc}"> Address to Bcc the message
<input type="text" name="emailsubject" size="49" value="$var{Subject}"> The messgae Subject
<input type="button" name="AddRec" value="Add Recpients" onclick="AddRecpients()"> Add person to send to
<input type="submit" name="Send" value="Send"> Send the message
<input type="reset" name="Submit22" value="Clear"> Clear the message box
<input type="button" name="AddRec" value="Add Recpients" onclick="AddRecpients()">  
<input type="button" name="SpellBtn" value="Spell Check" onClick="SpellCheck()"> Spell check the message
<input type="button" name="Attach" value="Attachment" onclick="Attachment()"> Add an attachment
<input type="submit" name="Draft" value="Save Msg"> Save as Draft
<input type="submit" name="Send" value="Send"> Send the message
<input type="hidden" name="emailmessage" value=""> The Message body
<input type="hidden" name="emailto" value=""> Address the eMail is to
<input type="hidden" name="emailcc" value=""> Address to CC message
<input type="hidden" name="emailbcc" value=""> Address to Bcc the message
<input type="hidden" name="emailsubject" value=""> The subject of the message
<input type="hidden" name="HtmlEditor" value=""> To use the HTML editor
<select name="emailfrom">
<option
value="$atmail->{username}@$atmail->{pop3host}">
$atmail->{username}@$atmail->{pop3host}
</option>
</select>		 Address to send the eMail from
<select name="emailpriority" >
<option value="0">Normal</option>
<option value="5">Low</option>
<option value="1">High</option>
</select>		 The Priority of the message
<textarea name="Body" style='visibility:hidden;position:absolute;top:0px;left:0px'>
$var{Msg}
</textarea>

<div id="plainmsg" style='visibility:hidden;position:absolute;top:0px;left:0px'>$var{Msg}

$var{Signature}
</div>

 The eMail Message and signature

addressbook.html

HTML Tag Description
<input type=hidden name="func" value="open">  
<input type=hidden name="add" value="1"> Add address to the Address book
<input type="text" name="Email" size="40" maxlength="64" value="$var{UserEmail}"> eMail address to add
<input type="text" name="FullName" size="40" maxlength="64" value="$var{UserFullName}"> Full name to add
<input type="text" name="Address" size="30" maxlength="64" value="$var{UserAddress}"> Address to add
<input type="text" name="City" size="30" maxlength="64" value="$var{UserCity}"> City to add
<input type="text" name="State" size="20" maxlength="64" value="$var{UserState}"> State to add
<input type="text" name="Country" size="35" maxlength="64" value="$var{UserCountry}"> Country to add
<input type="text" name="URL" size="40" maxlength="128" value="$var{UserUrl}"> URL to add
<input type="text" name="WorkPhone" size="20" maxlength="64" value="$var{UserWorkPhone}"> WorkPhone to add
<input type="text" name="HomePhone" size="20" maxlength="64" value="$var{UserHomePhone}"> Home phone ot add
<input type="text" name="Fax" size="20" maxlength="64" value="$var{UserFax}"> Fax to add
<input type="submit" name="Submit" value="Add Entry"> Submit the details to the address

settings.html

HTML Tag Description
<input type="hidden" name="func" value="settings">  
<input type="hidden" name="save" value="1">  
<input
type="text" name="RealName" size="40" value="$atmail->{RealName}">		 Users Full Name
<input type="text" name="ReplyTo" size="40" value="$atmail->{ReplyTo}"> Users Reply to address
<input type="checkbox" name="NewWindow" value="1"> Open messages in a new window
<input type="checkbox" name="EmptyTrash" value="1"> Empty the trash on logout
<input type="checkbox" name="HtmlEditor" value="1"> Use HTML editor toggle
<textarea name="Signature" cols="25" rows="5">$atmail->{Signature}</textarea> User Signature
<input type="text" name="Forward" size="40" value="$atmail->{Forward}"> User Forward eMail
<input type="submit" name="Submit" value="Save Settings"> Save the current settings
<select name="MboxOrder">
<option value="id">Recieved</option>
<option value="EmailSubject">Subject</option>
<option value="EmailFrom">From</option>
<option value="EmailDate">Date</option>
</select>		 Order to display messages in the mail boxes
<select name="Advanced">
<option value="1">Enable (default)</option>
<option value="0">Disable</option>
</select>		 The Message summary popup boxes in the Mail Boxes
<select name="MsgNum">
<option value="10">10</option>
<option value="25">25</option>
<option value="50">50</option>
<option value="100">100</option>
<option value="200">200</option>
<option value="All">All</option>
</select>		 Number of messages to desplay on the Mail Boxes
<select name="FontStyle">
<option value="Verdana">Verdana (default)</option>
<option value="Arial">Arial</option>
<option value="Courier">Courier</option>
<option value="Georgia">Georgia</option>
<option value="Times">Times</option>
</select>		 Default font for @Mail
<select name="UserLanguage">
<option value="">English (standard)</option>
</select>		 Default Language to use
<select name="LeaveMsgs">
<option value="1">Yes (Standard)</option>
<option value="0">No</option>
</select>		 Leave message on the POP server Toggle

<select name="designtype">
<option value="none">Select Design</option>
<option value="standard">Blue Sky</option>
<option value="purplehaze">Purple Haze</option>
<option value="grey">Grey sky</option>
<option value="custom">Custom Design</option>
</select>

 Interface color selection

<select name="TimeZone">

please add your time appropriate time zones

</select>

 User timezones

<select name="EmailHeaders">
<option value="Standard">Show Some (default)</option>
<option value="None">Show None</option>
</select>

 Desplay eMail headers when messages are read toggle

showmail.html

HTML Tag Description
<input type="hidden" name="Folder" value="$var{folder}"> The Folder to send selected message
<input name=submit2 type=submit value="Move" named="Submit"> Move message to folder
<input type="hidden" name="sort" value="$var{sort}"> sort messages
<input type="hidden" name="order" value="$var{order}"> Order of messges
<input type="hidden" name="Folder" value="$var{folder}"> The Folder to send selected message
<input type="hidden" name="start" value="$var{msg_pos}"> message number positon within inbox, for navigating
<select name="NewFolder">
$var{folderbox}
</select>		 Creates a new folder
$var{emails} The eMails listed

folders.html

HTML Form Description

<form method="post">
<input type="hidden" name="func" value="info">
$var{folders}
<input type="text" name="foldername" value="" size="30">
<input type="submit" name="creatembox" value="Create Mbox" >
</form>

 Display folders and create new ones
<form>
<input type="hidden" name="func" value="info">
<input type="text" name="SpamEmail" value="" size="30">
<input type="submit" name="spamadd" value="">
</form>		 Add eMail addresses to the SPAM list
<form>
<input type="hidden" name="func" value="info">
<select name="spamdel">
$var{spam_select}
</select>
<input type="submit" name="Submit3" value="">
</form>		 Delete an eMail address from the SPAM list
<form>
<input type="hidden" name="func" value="info">
<textarea name="AutoReply" cols="40" rows="7">$atmail->{AutoReply}</textarea>
<input type="submit" name="addreply" value="">
<input type="submit" name="deletereply" value="">
</form>		 Add / Delete an autoreply for all incomming messages
<form>
<input type="hidden" name="func" value="info">
<input type="text" name="sort_email" size="30">
<input type="text" name="sort_subject" size="30">
<select name="sort_box">
$var{folderbox}
</select>
<input type="submit" name="addsort" value="">
</form>		 Create auto message sorting to folders
<form>
<input type="hidden" name="func" value="info">
<input type="hidden" name="type" value="EmailAddress">
<select name="delete_sort">
$var{sort_email}
</select>
<input type="submit" name="delsort" value="">
</form>		  
<form>
<input type="hidden" name="func" value="info">
<input type="hidden" name="type" value="EmailSubject">
<select name="delete_sort">
$var{sort_subj}
</select>
<input type="submit" name="delsort" value="">
</form>		  

9. Style sheet information

Stylesheets are a simple and easy way of modifying the @Mail interface without changing any HTML code.

The @Mail interfaces use several different style sheets to be compatible to the majority of modern browsers and situations. They are listed as follows:

Style Sheet Name Implementation
atmailstyle.css General Stylesheet used within @Mail
atmailstyle-form.css Stylesheet used in the HTML forms.
atmailstyle-mail.css

Stylesheet used to display the eMail in the mailboxes
javascript/styleIE.css IE Stylesheet for login pages etc, listed as style$var{browser} in HTML code
javascript/styleNS.css Netscape Stylesheet for login pages etc, listed as style$var{browser} in HTML code

10. Editing the simple interface.

This simple interface differs from the professional interface in that it has no frames. To stop all files from having the same information, the simple interface has a header and a footer.

Each file must reference the header and footer such:

<--!Include="html/english/simple/header.html"--> above the html

<--!Include="html/english/simple/footer.html"--> below the html

The "html/simple/footer.html" must be a complete path and relative to the atmail directory.

Note: If you are editing the simple interface files from and HTML editor, make sure that the editor dose not add <html>...</html> or <body>...</body> etc , this will stop the header / footer system from running.

The .ehtml system works by replacing the html comment <--!Include="filename.ehtml"--> with the contents of that file. This system is completely transparent to the user and browser

11 .Related Technical / support information

For more information please contact info@calacode.com