This is the output
of the custom-written man page for the mail script:
Netmar
User Tools mail(1)
NAME
mail
SYNOPSIS
<form action="/cgi-bin/mail" method="POST">
<input type="hidden" name="to" value="EMAIL_ADDRESS">
<input type="TYPE" name="name">
<input type="TYPE" name="email">
<input type="TYPE" name="subject">
<input type="hidden" name="next" value="PAGE_TEMPLATE">
<input type="hidden" name="emailtemplate" value="EMAIL_TEMPLATE">
<input type="hidden" name="confirm" value="EMAIL_ADDRESS;
CONFIRM_TEMPLATE">
<input type="hidden" name="pgp" value="USERNAME;
PGP_KEY_ID">
<input type="hidden" name="require" value="VAR1
VAR2 ...; PAGE_TEMPLATE">
<input type="hidden" name="is_ccard" value="VAR1
VAR2 ...; PAGE_TEMPLATE">
<input type="hidden" name="is_email" value="VAR1
VAR2 ...; PAGE_TEMPLATE">
<input type="hidden" name="is_web" value="VAR1
VAR2 ...; PAGE_TEMPLATE">
...
</form>
DESCRIPTION
The mail CGI script is one of most powerful and flexible HTML
Form-to-Email conversion programs ever written. It allows the website
designer an extremely high level of control over its operation with
relatively little input
Basic operation is as follows:
1) The script reads all CGI input and assigns special CGI variables
to
their corresponding program variables.
2) The destination email address(es) supplied as the value of the "to"
CGI
variable is checked for validity in form. It must be a
compliant Internet email address. If the destination address
fails this check or is non-existent, the script exits and displays
a message to the user informing them that no valid destination email
address could be found.
3) Conditional requirements are checked. Various requirements specified
by the existence of the require, is_ccard, is_email, or is_web
CGI variables are checked against the contents of the submitted data.
If not met, the appropriate HTML page template is sent, parsed,
to the browser, and the script exits without sending its mail.
4) Email is sent. The email message is constructed by parsing the
specified email template, if any, encrypted if so specified, and mailed
to the destination specified in to CGI variable. The message subject,
sender, and from headers are set in accordance with the supplied data.
If specified in the form, a second, unencrypted email message may also
be sent to the person filling out the form.
5) Return page is displayed. The appropriate return template, if any,
is retrieved, parsed, and sent.
OPTIONS
The following CGI variables have special meaning to the mail script.
A
discussion of each follows.
Variable Name Value is treated as
------------- ---------------------------------------------------------
to Internet email address to which resulting email is sent
name Name of sender to be included in header of mail
email Email address of sender to be included in header of email
subject Message subject to be used for the outbound mail
next Template to be used for return page OR URL to which the
browser should be redirected after submitting data
emailtemplate Template to be used for constructing the mail message
confirm Return email address, followed by a semi-colon and a template
to be used to create an email message to be sent to the
sender of the form. Typically, this is used to create some
sort of confirmation message for the user of the form.
pgp Netmar username whose PGP public keyring should be used
followed by a semi-colon and the PGP User ID of the public
key within that keyring that should be used to encrypt
the outbound mail message.
require One or more space-delimited CGI variable names in the same
form which MUST have a non-empty value, followed by a
semicolon and a template to be displayed if one or more of
the supplied variables does not meet this requirement.
is_ccard One or more space-delimited CGI variable names in the same
form which MUST be a valid credit card number, followed by
a semicolon and a template to be displayed if one or more
of the supplied variables does not meet this requirement.
is_email One or more space-delimited CGI variable names in the same
form which MUST be an Internet email address, followed by
a semicolon and a template to be displayed if one or more
of the supplied variables does not meet this requirement.
is_web One or more space-delimited CGI variable names in the same
form which MUST be a proper WWW address , followed by
a semicolon and a template to be displayed if one or more
of the supplied variables does not meet this requirement.
The "to" Variable
The to variable takes a single Internet email address as an argument.
While it is not possible for the script to determine whether or not
the
address is valid, the address must comply with certain format
requirements. Specifically, it must begin with one or more alphanumeric
characters immediately followed by an @ symbol, which must then be
followed by a domain name that is at least a second-level zone or higher.
The "name" Variable
The name variable supplies the script with the full name of the person
sending the message. Its value is included in the header of the
message on the From: line.
The "email" Variable
The name variable supplies the script with the email address of the
person sending the message. Its value is included in the header of the
message on the From: line. No cross-checking is done to ensure that
the supplied value is a properly formatted email address, however, such
crosschecking can be done through application of the "is_email"
macro.
The text '<input type="hidden" name="is_email"
value="email;">' embedded
within the form would cause the mail script to check the value of the
email field and display the built-in error page if it were not a
properly formatted email address.
The "subject" Variable
The name variable supplies the script with the full name of the person
sending the message. Its value is included in the header of the
message on the Subject: line if no template is supplied.
The "next" Variable
The next variable supplies the script with either 1) the location of
a template to be used to construct the return page (the page returned
to the browser after submitting data) OR 2) the URL of a static
web page to display, beginning with "http://" or "https://"
If the
latter option is used, the browser is redirected to that URL. Note
that in such case, the data is NOT retrieved by the script and thus
cannot be parsed. If this information is incorrect or missing, the
script takes "its best guess" at a valid next page, and returns
a
"Message Sent" page with a link to the DocumentRoot of the
Virtual
Server on which the form was based.
The "emailtemplate" Variable
The emailtemplate variable supplies the script with the location of
a template to be used to construct the outbound email message. If this
information is missing or incorrect, the script uses a built-in template
that returns data one line per item in a "name=value" format.
The "confirm" Variable
The confirm variable instructs the script to generate a second email
message using the specified template to be sent to the email address
specified in the "email" variable using the supplied return
address as
the origin ("From:" address) of the message. If the email
variable
does not contain a valid email address, no separate error message is
presented and no confirmation message is sent. Thus, it is generally
wise to use the "require" and "is_email" variables
to require the
user to enter a valid email address in the email field.
The email generated by this directive cannot be encrypted.
The "pgp" Variable
Previously, it was commonplace for website owners to declare their forms
"secure" just because they were on a secure server, even though
the email
generated by those forms was sent unencrypted (and thus vulnerable to
eavesdropping).
The pgp variable instructs the script to encrypt the outbound email
message using the specified public key within the public keyring
belonging to the Netmar user whose username is supplied. Generally,
this would be the username of the owner of the form, who may then
decrypt messages using his/her private key.
See the pgp(1) man page for more info on the PGP encryption package.
Note that ALL copies of the outbound message are encrypted using the
same key and that NO unencrypted copy of the message is sent. Use
of this feature is STRONGLY recommended for any form that accepts
sensitive data such as credit card numbers. This encryption provides
for a completely encrypted path for data from a secure form to travel,
allowing forms to be truly secure.
The "require," "is_ccard," "is_email,"
and "is_web" Variables
The conditional operation variables allow the script to make some very
basic decisions about how to operate and what to show the user based
on
the data the user returns. All four launch routines that use the exact
same argument format, where the value passed should be formatted as:
"VAR1 VAR2 VAR3 ... ; TEMPLATE"
where "VAR1 VAR2 VAR3 ..." is one or more variables which
must satisfy
the given macro, and TEMPLATE is the template to be displayed if the
macro is NOT satisfied. For example, the line:
<input type="hidden" name="is_web" value="oldurl
newurl; /mypage.phtml">
would invoke the is_web routine and check the values of the CGI
variables "oldurl" and "newurl." If either value
did not contain a
properly formated WWW address, then the template mypage.phtml, located
either in the system root directory, or within the DocumentRoot directory
of the Virtual Server where the form is located, would be parsed and
displayed, and no mail would be sent.
It should be noted that A BLANK ENTRY FOR ANY OF THE "is_"
VARIABLES
IS CONSIDERED VALID and will not trigger the error notice. Thus, if
a non-blank entry is desired, the "require" directive should
ALSO be
used for that variable.
TEMPLATE SPECIFICATION
All templates are located using the same mechanism. First, the supplied
template is treated as an absolute system path. If no leading "/"
exists, it is added. If the file is not found by that method, it is
then treated as being within the DocumentRoot directory of the Virtual
Server on which the form is based. The DocumentRoot directory is
prepended to the path and the resulting path is searched. If the file
is still not found, the search is abandoned and whatever built-in
template that exists for the purpose is used.
TEMPLATE PARSING
Perhaps the most powerful feature of the mail script is its ability
to
send customizable emails and responses. This is possible due to a
fairly advanced file parsing engine that allows, among other things,
CGI variables to be inserted anywhere in a plain text (or HTML) file.
This capability, in combination with a set of embedded macros and
conditional expressions, allows for the creationg of a highly
customized template to create response emails and HTML documents.
Variable Subtitution
The heart of the parsing engine is the variable substition engine.
This is basically a simple search and replace engine which recognizes
specially formatted substitution codes of the form ${variable}.
Occurances of a subtitution code bearing the name of a particular
variable are replaced by the value of that variable. For instance,
if a HTML form returned the variable/value pairs color=green and
size=large, a template line that read
I have a ${size} ${color} apple.
would be converted to
I have a large green apple.
Logical OR'ing
Variable names within a substition code can be logically OR'ed through
use of the | symbol. This allows for the use of a template by multiple
forms as a particular substitution code can be made to match more than
one CGI variable. The first existing CGI variable listed within the
substitution code will be used. For example, if a form returned the
variable/value pairs city=Durham and how=driving, a line that read
I am ${when|how|why} to ${place|continent|city}.
would be converted to
I am driving to Durham.
Macros and Conditional Expressions
The parsing engine allows for various macros within the parsed file.
All lines that begin with a "." are treated as macros. ALL
MACROS
MUST BEGIN WITH A DOT. Next comes the macro name, then any arguments
it may take. Macros that allow line information on the same line must
be terminated with a period "." Currently, these macros are
recognized:
# - Comment. Entire line is ignored
inc FILE - Specified file is included, unparsed.
numsub<=>X.- line is output only if the number of substitutions
performed on that line satisfies the given expression.
e.g.
.numsub>4.Whatever...
The above will cause "Whatever..." to be output if there are
more
than 4 total substitutions performed on that line.
nzlsub<=>X. - line is output only if the number of subtitutions
resulting in one or more characters being placed on the line
satistisfies the given expression. This is identical to numsub
except that the string substituted in must be 1 or more characters
in length to increment the counter. This is useful for only
printing a line if an HTML form input type CHECKBOX is checked as
a value is returned only if it is checked.
numarg<=>X. = line is output if the total number of CGI variables
passed satistfy the given expression
Advanced Macros
The following macros allow for advanced conditional processing of
template data. However, their implementation is sufficiently complex
so as to confuse the average user. Use of these macros is UNSUPPORTED
and should only be attempted by advanced programmers.
Both macros rely on ordinal substitution codes (of the form
${1} ${2} ...). Data supplied to the parsing engine is numbered in
the order supplied. It is inherently difficult to use this information
reliably due to the fact that the CGI specification does not require
the browser to submit form data in the order it appears in the form.
So of course, browsers exist that do not, most notably, the AOL 2.5
and earlier browsers. However, the engine provides this capability,
and the following macros are available in any program that uses the
engine. Actual use of these macros within the CGI arena, however,
is risky. That is why these macros are UNSUPPORTED.
rep=A,B,C. - line is printed A times using B arguments each time
starting with argument C. Ordinal argument handles are available
through a set of transposed codes of the form ${rep:X}, where X
is the (C+X-1)'th argument. For instance, ${rep:1} would represent
the argument number indicated by C, while ${rep:2} would represent
the very next argument.
trep=T,A,B. - line is printed repeatedly using A arguments each time
starting with argument B each time. Each argument is intepreted as a
list of tokens separated by separator T. The line is printed
repeatedly until all arguments run out of tokens. It is expected
that each of the specified arguments would have the same number of
tokens, but this is not necessary. It should be noted that at
present, the author cannot imagine a situation where one might use
the trep macro with data submitted via CGI, but if you can think
of one, more power to ya'.
All macros are executed AFTER substitution. Therefore, it is possible
for a macro to vary depending on variables placed on the same line.
Even
the macro itself can be specified in this fashion. For instance, placing
${what_to_do} ${argument}
on a line could cause the line to be interpreted as an output line,
or a macro, depending on what the values of CGI variables what_to_do
and argument are.
FILE NAMING CONVENTIONS
Observing a practical file naming convention can greatly increase the
simplicity of processing forms with mail. The following is a simple
recommended convention for choosing filenames. All files designed for
a
particular form should have the same main name as the form file.
The parseable HTML file to be used to create the return page sould end
in ".phtml". The email template file should end in ".etemp".
The file
to be displayed for failure of the is_ccard routine should end in
".isc.phtml". The file to be displayed for failure of the
is_email
routine should end in ".ise.phtml". The file to be displayed
for failure
of the is_web routine should end in ".isw.phtml". The file
to be
displayed for failure of the require routine should end in ".req.phtml".
This convention allows all files designed for a particular form to have
the same name, each with a different file extension. For example, for
an orderform, the files may be named:
orderform.html
orderform.phtml
orderform.etemp
orderform.isc.phtml
orderform.ise.phtml
orderform.isw.phtml
orderform.req.phtml
