Template Support in NeoMail
===========================

After installing NeoMail, default templates will be installed in
/var/neomail/templates, or the templates subdirectory of wherever you told
setup.pl to use as neomail's root directory.  Users may modify these files to
achieve a more customized look for their installation, while still allowing
NeoMail to plug in its specially-generated information where necessary.  Here
are the details, I think they're pretty comprehensive:

GENERAL INFO
============

Every text trigger that will be substituted for by NeoMail is surrounded by
3 at-signs.  For instance, the trigger to substitute the user's style-chosen
font face is @@@FONTFACE@@@.  There are certain substitutions of a more
cosmetic nature mostly, that may occur in ANY template, ANY number of times.
Other substitutions are only performed in certain template files, based on the
type of page being generated.  Information about these will follow.  For now,
here are the text triggers usable in ALL templates, and what they do:

@@@LOGO_URL@@@ - Inserts the URL of the logo specified by the variable $logo_url
                 at the top of the scripts.
@@@BACKGROUND@@@ - Inserts the hex-coded color specified in the style file as
                   the "background" color.  In truth, this is not normally seen
                   because the background image is loaded in front of it.
@@@TITLEBAR@@@ - Inserts the active-style-specified titlebar color code.
@@@TITLEBAR_TEXT@@@ - Inserts the style-specified color code for titlebar text.
@@@MENUBAR@@@ - Inserts the style-specified color code for a menu bar. (The area
                where available actions are displayed, normally just under the
                title bar.)
@@@WINDOW_DARK@@@ - Inserts the style-specified "darkened window" color.
@@@WINDOW_LIGHT@@@ - Inserts the style-specified "light window" color.
@@@ATTACHMENT_DARK@@@ - Inserts the style-specified "dark attachment" color.
@@@ATTACHMENT_LIGHT@@@ - Inserts the style-specified "light attachment" color.
@@@COLUMNHEADER@@@ - Inserts the style-specified column header color, as seen in
                     the header display page of NeoMail.
@@@TABLEROW_LIGHT@@@ - Inserts the style-controlled light color that is used
                       during alternating-color display of table rows.
@@@TABLEROW_DARK@@@ - Inserts the style-controlled dark color that is used
                       during alternating-color display of table rows.
@@@FONTFACE@@@ - Inserts the style-specified font face information.
@@@SCRIPTURL@@@ - Inserts the relative URL for the neomail.pl script, as
                  specified in the script headers or during setup.pl.
@@@PREFSURL@@@ - Inserts the relative URL for the neomail-prefs.pl script, as
                 specified in the script headers or during setup.pl.
@@@CSS@@@ - Inserts the cascading style sheet code included in the active style.
@@@VERSION@@@ - Inserts the running NeoMail version number.
@@@REALNAME@@@ - Inserts the user's real name as specified in their prefs.

Examples of these in use can be seen all throughout the default style files.


PAGE-SPECIFIC INFO
==================

Here is the list of each template file, along with any keywords specific to that
page.

=============================================================================

header.template - Loaded at the beginning of all pages.  Includes the page's
                  title, background image, etc.  It contains no page-specific
                  keywords.

=============================================================================

footer.template - Loaded after each page.  Closes the HTML tags, etc.  Again,
                  no specific keywords.

=============================================================================

viewfolder.template - Displays the headers of messages in the selected folder.
   Special keywords:
   @@@STARTFOLDERFORM@@@ - initializes the folder selection dropdown form that
                           appears at the top-left of the display be default.
                           Must be followed by FOLDERPOPUP and then ENDFORM
                           before another form is started.
   @@@FOLDERPOPUP@@@ - Controls the actual placement of the drop-down box for
                       folder selection.
   @@@ENDFORM@@@ - Used throughout to end the scope of a form.
   @@@NUMBEROFMESSAGES@@@ - Pretty self-explanatory.  Prints the message that
                            says "No messages," "5 messages (2 unread) - 64KB"
                            or whatever.
   @@@MENUBARLINKS@@@ - Prints the row of links that allow users to access
                        "Compose," "User prefs," etc.
   @@@STARTPAGEFORM@@@ - Initializes the form that allows navigation between
                         pages of messages.  Should be followed by PAGECONTROL
                         and ENDFORM before another form is started.
   @@@PAGECONTROL@@@ - Prints out the arrows and page number entry portion of
                       the page control form.
   @@@STARTMOVEFORM@@@ - Starts the form that allows for movement of messages.
                         For it to work as intended, the code should be left
                         in the default template that provides for the check
                         all functionality.  You'll know it when you see it.
                         this form should span the display of all rows in the
                         message header display table.
   @@@MOVECONTROLS@@@ - Prints the actual submit button and dropdown folder list
                        for the move form.
   @@@DATE@@@ - Prints the date column header, with the right up/down arrow if
                applicable.
   @@@SENDER@@@ - Prints the sender column header, with the right up/down arrow
                  if applicable.
   @@@SUBJECT@@@ - Prints the subject column header, with the right up/down
                   arrow if applicable.
   @@@SIZE@@@ - Prints the size column header, with the right up/down arrow if
                applicable.
   @@@DELETE@@@ - Prints the delete column header, using either "Trash" or
                  "Delete" based on the action for the current folder.
   @@@HEADERS@@@ - Prints the actual rows listing message headers with
                   checkboxes.

=============================================================================

readmessage.template - Displays the content of a given message that was clicked
                       on.
   Special keywords:
   @@@MESSAGENUMBER@@@ - Currently viewed message number.
   @@@MENUBARLINKS@@@ - List of actions to perform from this page.
   @@@MESSAGECONTROL@@@ - Allows forward-reverse navigation of messages without
                          going back to inbox.
   @@@STARTMOVEFORM@@@ - Initializes the folder-selection form for moving
                         messages.
   @@@MOVECONTROLS@@@ - Places the move popup-menu and button on the page.
   @@@HEADERSTOGGLE@@@ - When clicked, toggles All Headers/Simple Headers
   @@@HEADERS@@@ - Displays the headers for the message.
   @@@BODY@@@ - Displays the body of the message, with necessary attachment
                links.

=============================================================================

composemessage.template - The compose message form, also used when forwarding
                          or replying.  Don't screw with the Javascript in
                          the to: links unless you know what you're doing, or
                          you may break the address book feature.
   Special keywords:
   @@@BACKTOFOLDER@@@ - Prints the link to go back to the last folder display.
   @@@STARTCOMPOSEFORM@@@ - Initialized the compose form with hidden values and
                            all other manner of goodness.
   @@@ESCAPEDFROM@@@ - The user's from: address, escaped so that <> displays
                       correctly.
   @@@TOFIELD@@@ - Text field to type in recipients for the message.
   @@@CCFIELD@@@ - Text field for CC recipients.
   @@@BCCFIELD@@@ - Text field for BCC recipients.
   @@@REPLYTOFIELD@@@ - Text field for the user to enter an alternate reply-to
                        address for themselves.
   @@@ATTACHMENTFIELD@@@ - Attachment field, with a handy-dandy browse button.
   @@@SUBJECTFIELD@@@ - Users can type a subject here.
   @@@BODYAREA@@@ - Textarea for message contents entry.
   @@@SENDBUTTON@@@ - The send button!
   @@@ENDFORM@@@ - Should be after the message composition form components, and
                   before the @@@STARTCANCELFORM@@@ keyword. And again to end
                   the cancel button form.
   @@@STARTCANCELFORM@@@ - Cancel button initialization.
   @@@CANCELBUTTON@@@ - Actual cancel button.
   @@@SESSIONID@@@ - Needs to be used in the Javascript portion to allow the
                     address book display to work properly.  Since you shouldn't
                     normally be messing with this portion, you probably won't
                     need to touch it.

=============================================================================

editfolders.template - The page where users can add/delete folders.
   Special keywords:
   @@@MENUBARLINKS@@@ - prints the menu bar links, currently "back to folder."
   @@@STARTFOLDERFORM@@@ - Initializes the folder entry form.
   @@@FOLDERNAMEFIELD@@@ - Inserts the field for name entry.
   @@@ADDBUTTON@@@ - Prints the add button.
   @@@ENDFORM@@@ - Standard form-closing HTML. 
   @@@FOLDERS@@@ - Starts listing the currently existing folders in
                   alternating-color rows.  Keep in mind that the table needs
                   to have been started already, as in the default template.
                     
=============================================================================

editaddresses.template - The page where users can add/delete addresses from
                         their address books, or click import to import their
                         netscape/outlook express addresses.
   Special keywords:
   @@@FREESPACE@@@ - Free address book space in kilobytes
   @@@MENUBARLINKS@@@ - prints the menu bar links, currently "back to folder"
                        and "import."
   @@@STARTADDRESSFORM@@@ - Initializes the address entry form.
   @@@REALNAMEFIELD@@@ - Inserts the field for name entry.
   @@@EMAILFIELD@@@ - Inserts the e-mail address entry field.
   @@@ADDBUTTON@@@ - Prints the add/modify button.
   @@@ENDFORM@@@ - Standard form-closing HTML. 
   @@@ADDRESSES@@@ - Starts listing the currently existing addresses in
                     alternating-color rows.  Keep in mind that the table needs
                     to have been started already, as in the default template.

=============================================================================

firsttimeuser.template - Prints the welcome message for first-time users.
   Special keyword:
   @@@CONTINUEBUTTON@@@ - Shows a button that takes the user to the prefs
                          screen for the first time.

=============================================================================

importabook.template - The page that allows a user to upload a Netscape or
                       Outlook Express address book for import.
   Special keywords:
   @@@FREESPACE@@@ - Prints the free space available (in kilobytes) for the
                     address book.
   @@@STARTIMPORTFORM@@@ - Initializes the import form.  Form should contain
                           @@@MUARADIOGROUP@@@, @@@IMPORTFILEFIELD@@@, and
                           @@@IMPORTBUTTON@@@ before the corresponding
                           @@@ENDFORM@@@ is called to funtion properly.
   @@@MUARADIOGROUP@@@ - prints the radio buttons that let the user choose
                         which mail reader they are importing from.
   @@@IMPORTFILEFIELD@@@ - Provides the filefield for address book import
                           file selection.
   @@@IMPORTBUTTON@@@ - The button that submits the import form and performs the
                        import.
   @@@STARTCANCELFORM@@@ - Initializes a cancel button form.
   @@@CANCELBUTTON@@@ - the (surprise!) cancel button itself.

=============================================================================

login.template - The main login screen.
   Special keywords:
   @@@STARTFORM@@@ - Initialize the login form.
   @@@USERIDFIELD@@@ - Prints the field for User ID.
   @@@PASSWORDFIELD@@@ - Pretty much says it all. :)
   @@@LOGINBUTTON@@@ - Submits the login request.
   @@@CLEARBUTTON@@@ - While not necessary, this allows a user to clear their
                       entered username and/or password should they need to
                       leave the terminal, so I'd recommend it.
   @@@ENDFORM@@@ - After all form elements have been printed.

=============================================================================

passwordincorrect.template - Printed when an invalid login is attempted.  No
                             special keywords.

=============================================================================

prefs.template - The main preferences screen, displayed by default by 
                 neomail-prefs.pl.  It should be noted that if you don't want
                 to allow a user easy access to a preference here, you can
                 simply leave that field out.
   Special keywords:
   @@@STARTPREFSFORM@@@ - General form initialization junk.
   @@@REALNAME@@@ - Prints "FOR FIRST LAST" using the user's first/last name
                    if available in the saved prefs.
   @@@LANGUAGEFIELD@@@ - Prints a drop-down list of available language
                         translations.
   @@@REALNAMEFIELD@@@ - Where a user can type their real name. 
   @@@REPLYTOFIELD@@@ - Users can enter their desired reply-to address here, if
                        different from their From: address.
   @@@STYLEMENU@@@ - A drop-down list of available styles.
   @@@SORTMENU@@@ - Drop-down list of sort-by choices.
   @@@HEADERSMENU@@@ - To select All/Simple default header display mode.
   @@@SIGAREA@@@ - A textarea for entering a signature to be appended to
                   outgoing messages.
   @@@BUTTONS@@@ - Save/Cancel buttons. Cancel isn't shown the first time this
                   screen is displayed for a new user.

=============================================================================

prefssaved.template - A simple "Preferences saved" dialog, displayed after 
                      saving.
   Special keyword:
   @@@CONTINUEBUTTON@@@ - Prints a button to click to continue on to the folder
                         display.

=============================================================================

senderror.template - Will be displayed if NeoMail encounters errors sending
                     a message using sendmail.  This is kinda iffy, as some
                     sendmail executables (used by different MTAs) return
                     alternate error codes. No special keywords.

=============================================================================

sessiontimeout.template - Displayed when a user needs to go back and re-login
                          because their session has timed out.  No special
                          keywords.
