PC World 2002 June/PCWorld_2002-06_cd.bin/Software/Topware/pegasus/w32-401.exe/TEMPLATE.TXT

Text File | 1999-11-22 | 21KB | 498 lines

----------------------------------------------------------------------
                     Pegasus Mail Message Templates
----------------------------------------------------------------------
                          Pegasus Mail System,
       Copyright (c) 1990-99, David Harris, All Rights Reserved.
----------------------------------------------------------------------


Contents:

1:              Overview of Message Templates
2:              Types of Templates
3:              Using Templates within Pegasus Mail
4:              The Message Template Script Language
  4.1:          String literals
      4.1.1:    Filenames
  4.2:          Optional parameters
  4.3:          Command substitutions
  4.4:          Script language commands



1: Overview of Message Templates
--------------------------------

Imagine that you're the web master for your Internet site; you receive a
huge amount of mail for much of which the answer is essentially the
same... You laboriously reply to the message, remove the pieces you don't
want, type in your canned response, then send the message. Wouldn't it be
good if there was some way of automating all of this? Well, there is --
Message Templates.

A Message Template is simply a script that tells Pegasus Mail how to
compose a mail message. The template script commands allow you to set any
address or feature field, include the original message for replies (or a
portion of the message), change or modify addresses, add attachments and
generally give you complete control over the shape of your automatically-
generated message. What's even better, you can define variables in
templates: when you use the template, Pegasus Mail will prompt you for
values for the variables it contains; the script language can then take
the values you enter, manipulate them, and insert them seamlessly into
the generated message.

Using a message template, you can generate a complex mail message and
send it with only a couple of keystrokes.

What uses might you have for a template? Here are some ideas:

   * Helpdesk submissions (as per the sample HELPDESK.PM5 template)

   * Mail server management forms (to simplify the process of
     subscribing to and unsubscribing from lists)

   * Forms: any kind of complex data-entry based mail form could
     be generated using a template

   * Order submission

   * Automated replies


2: Types of templates
---------------------

Pegasus Mail supports two types of templates - those used to create new
messages from scratch, and those used to create replies to messages.
Template files are simply plain text files containing template script
language commands, one per line.

Templates used to create new messages have the extension .PM5; the name
portion can be anything you wish.

Templates used to create replies to messages have the extension .PM6; once
again, the name portion can be anything you wish.

For both types of template, the script language's TITLE command must be
the first line in the file, so that Pegasus Mail can show the name in its
selector window. Pegasus Mail will not burrow through a template file
looking for a TITLE command if it is not on the first line.

Template files can be located in your home mailbox directory, or may be
placed in the same directory as the Pegasus Mail executable program, in
which case they become system-wide and are made available to all users
running that copy of the program. There is no effective limit on the
number of templates you can define.

For now, in order to create a template file you must use a text editor of
some kind - for instance, the Windows NOTEPAD applet. If you use NOTEPAD,
make sure that the Wordwrap option is turned off - each line in a
template file must contain a single command and you cannot run lines
together. Future versions of Pegasus Mail may include a user-interface for
creating template files.


3: Using templates within Pegasus Mail
--------------------------------------

You can create a new message using a template by selecting Template...
from the New Message submenu of the File menu. This will open a dialog
listing all the templates available on your system. Select the template
you want to use by highlighting it and clicking Open, or by double-
clicking it. A window will open prompting you for any variables the
template uses; at this point, you can choose whether to open a new
message editor window filled out with the message created by the
template, or simply to send the message without further ado.

You can use a template to create a reply to a message in one of two ways:

1: Right-click the message and choose "Reply using template..." from
   the popup menu

2: Highlight the message, then hold down <Shift> as you press the
   "Reply" button, or else hold down <Shift> and press the R key.



4: The Message Template Script Language
---------------------------------------

The script language used by Pegasus Mail templates is very simple. Each
command in the file must appear on a single line of its own -- commands
may not wrap lines, nor may more than one command appear on a single
line. Lines starting with \, * ; or # are treated as comments and are
ignored.


4.1: String literals

Most template script commands in the language accept strings as
parameters. String literals of this kind must be entered in quote
characters if they contain spaces or special characters.

For example, if you want to use the "insert" command to write the string

   Mary had a little lamb

into an outgoing message, you would need to enter the command like this:

   insert "Mary had a little lamb"

since otherwise, only the word "Mary" would be inserted.

If your string contains a quote character, or a backslash character, then
you will need to perform a small amount of conversion. So, if you want to
insert the string

   Mary had a "little" lamb

you would have to enter the "insert" command like this:

   insert "Mary had a \"little\" lamb"

These rules for string construction apply in all places throughout the
script language.


4.1.1: Filenames

Filenames are treated as strings by the script language, and as such are
subject to the same rules. In particular note that long filenames
containing spaces will need to be quoted, and that '\' characters will
need to be doubled in file paths... So, if you wanted to use the include
command to include the file

   c:\docs\Mary's "little" lamb

You would need to form the command as

   include "c:\\docs\\Mary's \"little\" lamb"


4.2: Optional parameters

Some script commands are shown as having "optional" parameters. This
notion needs some clarification... A parameter may be omitted only if all
the parameters following it are also omitted - it is not possible to omit
only one parameter from the middle of a list.

So, using the "include" command as an example, if you wanted to include a
file in quoted format, you would have to include the "0" value for the
count parameter as well.


4.3: Command substitutions

Practically any string parameter to a script command can contain command
substitutions: these are special character sequences that are replaced by
variables or other information when they are encountered. Pegasus Mail
recognizes the following command substitutions in any place where they
may be used:

   ~vvariable_name~   The current value of a template script variable
   ~z                 A single newline (CR/LF)
   ~f                 The "from" field of the original message
   ~s                 The "subject" field of the original message
   ~r                 The preferred reply address for the message
   ~kfieldname~       Any field from the original message
   ~n                 The current user's basic username
   ~i                 The current user's Internet e-mail address
   ~8                 The current user's username truncated to 8 chars
   ~p                 The current user's personal name preference
   ~d                 A random integer expressed as 4 hex digits
   ~y                 The current date and time in RFC822 format
   ~%name%            The value of environment variable %name%
   ~lname~l           The user's address looked up from a synonym file
   ~a                 The Pegasus Mail executable directory
   ~h                 The current user's home mailbox
   ~w                 The current user's new mailbox
   ~~                 A single tilde (~).

Examples:

   Assuming that the current user's name is "david" and the variable
   "sub" has been assigned the value "your order", the string

      "This is a message from ~8, regarding ~vsub~"

   would yield the following string after substitution:

      "This is a message from david, regarding your order."

Command substitution is the single most powerful feature of the scripting
language used for templates, and a good understanding of what it can do
is essential for writing useful scripts.


4.4: Script language commands

The following commands are valid in template scripts.

   title      Set the title for a template script
   helpfile   Set the help file for a template script
   picture    Add a picture to the variable prompt dialog
   text       Add a line of informational text to the prompt dialog
   option     Set options controlling the way the template is processed

   string     Create a string variable for the script
   set        Set a message field or variable value
   insert     Write a formatted line into the message body
   include    Include a file or the original message body
   attach     Attach a file to the message

   extract    Extract elements from an e-mail address
   lookup     Look up an item from a list using a key value

   chain      Execute another template when the current template finishes


# title <string>

Set the title for the script file. string can be any string up to 50
characters in length, and can contain all command substitutions except
for variables, which are not defined at the time this command is
processed.


# helpfile <filename> [section]

Set the help file which should be accessed when the user clicks the Help
button in the variable prompt dialog. filename should be a full reference
to any valid Windows Help file (*.HLP) on your system, and may contain
all command substitions except for variables, which will have not been
defined at the time this command is processed. section is an optional
integer value that indicates the context help section within the help
file that should be presented when the help button is pressed. If it is
absent, section 0, the table of contents, is presented.


# option <option_name> = <value>

This command controls aspects of the way the template behaves as it is
being processed. One option_name value is currently defined:

   "EDITOR" = "Yes" or "No".
   - Determines the state of the "Send message without opening a message
     editor" control in the template's variable dialog.

   Example:  OPTION EDITOR = NO
   - Checks the "send without editor" control by default.


# string <name> ["Default"] ["Prompt"] [len] [flags]

Define a variable for use within the script. A maximum of 20 variables
may be defined for any script. name is the name for the variable; it must
not contain spaces, and is not case-sensitive (so var1 and VAR1 are
considered the same). All the parameters following the name parameter are
optional, and you can end the string early if you wish (you cannot omit a
parameter if you need to supply a parameter following it on the line).
"default" is a string which should be used as a default value for the
variable: if it contains spaces or special characters, it must be
enclosed in quotes (see "String literals", above, for more information).
If this parameter is omitted, the default value is an empty string.
"prompt" is the string Pegasus Mail should place next to the editing field
in the variable prompt dialog. If omitted or zero-length, Pegasus Mail
will not prompt the user for a value for this variable. "len" is an integer
defining the maximum allowable length of this variable. If omitted, the
default is "no limit". "flags" defines the format and type of the variable:
the following flag values are available:

   multiline       creates a multi-line variable
   address         creates an e-mail address variable
   filename        creates a filename variable
   password        creates a password variable
   list            creates a list - see below for more details
   uppercase       specifies that the variable must be all in uppercase

Only "uppercase" may be used with other values.


Creating LIST variables

When you use the LIST flag in a STRING statement, you create a variable
that has a list of possible values from which the user can select. LIST
variables require that you provide a DEFAULT value for the variable,
which contains the list of possible values the variable can have. The
first character in the default value should be the character used to
separate the list items from each other, and the remainder of the default
value should be the items, separated by that character.

Example: you want to allow the user to select from the values "Red",
"Green" and "Blue": your string statement would look like this:

   string v1 ";Red;Green;Blue" "Select a colour" 0 list


# set <field> = <"value">
or set variable <variable_name> = <"value">

The first form of this command sets a field within the mail message being
generated to the specified value. field may be one of the following:

   to
   cc
   bcc
   reply-to
   subject
   identity      (all take an obvious string parameter)

   urgent
   confirm-reading
   confirm-delivery
   copyself
   volatile
   mime          (all take either a "Y" or "N" parameter)

   header        (a fully-formed e-mail header including the keyword)
   encrypted     ("encryptor_name", "password", "flags" - see below
                  for more details).

When encrypting a template message, use the "encrypted" parameter to the
set command. "encryptor" is the name of the module that should be used
for encryption - to use the Pegasus Mail built in encryptor, use the name
"builtin". "password" is the password for the message - this can be up to
96 characters in length. "flags" controls the type of encryption
performed; to encrypt a message, set it to 1; to add a digital signature
to the message, set it to 4; to perform both operations, set it to 5.

The "volatile" parameter tells Pegasus Mail to write the message directly
to final form when sending using the built-in SMTP transport. You will
need to set this to "Y" if you are attaching files that will be deleted
once the template has been processed.

The second form of the "set" command sets the value of any defined
variable.

Both forms of this command support all command substitutions for the value
parameter. To copy the value of one variable to another, use an
expression containing the ~v command substitution, like this:

   set variable v1 = "~vv2~"


# insert <"string">

Write data into the body of the message being generated. string can
contain any command substitution: if it does not contain a ~z
substitution to force a line break, then the next insert command will
write data onto the same line in the body. A single insert command may
not insert more than 1024 characters into the message body.


# include <filename> [count] [flags]
or include message [count] [flags]

Include either a text file, or the body from the message to which a reply
is being generated. The text from the file or message is included as-is
into the message body - command substitutions are not performed on the
included data. The filename parameter may contain any valid command
substitutions. If "count" is present and non-zero, only that many lines of
the included file or the body of the included message will be read. The
"flags" item can be any combination of the following values:

   quoted     "Comment-out" the included text using "> "
   noheaders  If the file is a message, omit its RFC822 headers
   keyheaders If the file is a message, include only "significant" headers
   nobody     If the file is a message, omit the message body
   message    Only valid for files: the file is an RFC822 message


# attach <filename> [type] [encoding] ["Desc"]

Attach a file to the generated message. Only "filename" is a mandatory
parameter - the others can be omitted and are sensibly defaulted. Any
valid command substitution can be used in the filename. If the filename
contains spaces, it must be quoted. "type" is any string describing the
type of the file - for instance, "RTF_FILE". It must not contain spaces
and is not constrained to the list of possible values inside Pegasus Mail
itself. "encoding" is an integer value that specifies how the file should
be encoded for transfer; the following values are defined - 0 (Pegasus
Mail decides), 1 (No encoding - very dangerous), 2 (ASCII text), 3
(UUencoding), 4 (BinHex 4.0) and 5 (Basic MIME encoding). Unless you are
sure of what you are doing, use 0 for this field. "desc" is a textual
description of the file; it may contain any text, including spaces, and
is truncated at 63 characters.


# picture <flags> <filename>

Add a picture at the top of the variable prompt dialog. The picture
specified by filename must be a Windows BMP file in 16 or 256 colours:
owing to quirks in the way Windows handles 256 colour bitmaps, we
strongly recommend that you use 16-colour bitmaps if your display runs in
256 colour mode or lower. For the Win16 version of Pegasus Mail, the
bitmap must not be larger than 60,000 bytes. You may use any command
substitution in the filename parameter. The bitmap is centred
horizontally in the display and the dialog will adjust size to fit the
vertical dimensions of the image. Exactly one image may be added to the
dialog.

flags will be used in future to offer extra formatting options. For now,
it is unused, must be present, and should be set to zero.

Note: if the filename contains spaces or special characters, it must be
enclosed in quotes.


# text <flags> <"string">

Add a line of descriptive text to the dialog presented to prompt for
script variables. The line of text is added above any variable editing
fields, and below any picture defined using a picture command. You may
specify up to 10 lines of descriptive text, and each line may contain any
valid command substitution. The "flags" parameter will be used in future,
but should currently be set to zero.

To introduce a blank line between groups of lines, use a text statement
with an empty quoted string - like this: text "".


# extract address <var1> <var2>
or extract text <var1> <var2>
or extract user <var1> <var2>
or extract domain <var1> <var2>

Extract a component from an e-mail address. "var1" refers to the variable
containing the address to be manipulated. "var2" is the variable where
the result of the manipulation should be placed - it can be the same as
"var1".

   extract address    yields the minimum form of the e-mail address
   extract text       yields the personal name field from the address
   extract user       yields the simple user name portion of the address
   extract domain     yields the domain portion of the address


# lookup "string" <var1> <var2> <var3>

Attempt to locate the string "string" in the list variable "var1"; if a
match is found, note the position in the list where the item was matched,
then copy the item at the same ordinal position in the list variable
"var2" into the variable "var3". See above under the description of the
"set" command for more information on list variables. It is an error for
either "var1" or "var2" to be anything other than a list variable. If
"string" cannot be found in "var1", variable "var3" is not changed.

Example: list variable "v1" contains "Monday", "Tuesday" and "Wednesday"
list variable "v2" contains "Open", "Closed" and "Open".

The command

   lookup "Tuesday" v1 v2 v3

will result in variable v3 containing the value "Closed".

A common form of this command will use the current value of "var1" as the
string parameter, using the command substitution "~vvar1~".


# chain "filename"

Execute another template when the current template completes. "filename"
should be the path to a valid template file, and may contain command
substitutions. Only one "chain" command may be used per template. If the
current template is cancelled by the user, the chain command will not be
executed.