The MailSerf Manual
[ Usage
| Input Preprocessing
| Predefined Inputs
]
Usage
The correct, expected way to use mailserf in an HTML form is something
like this:
<form action="/cgi-bin/mailserf" method="POST">
...
</form>
where the "..." is subsituted for whatever you want in the form.
I recommend using the method POST instead of GET
to prevent the entire contents of the submitted form from being seen as the
resulting URL once submitted. If that was a confusing sentence, change
POST to GET in a form that you use, submit it, and
then check out the URL that results to see what I'm talking about.
Input Variable Preprocessing
All of the form inputs are processed before the e-mail
message is generated. Any input can be categorized as follows:
- control: These inputs are used to configure some feature of
mailserf. All have a prefix of
ctl: in the input name.
Any control inputs that are not expected by mailserf are ignored,
and are not included in the e-mail message that is produced.
- header: These inputs are included as "header" lines
in the e-mail message that is produced. All have a prefix of
hdr: in the input name.
- body: Any inputs that are not control or header definitions
are determined to be values that should be included in the body of the
produced e-mail message. In other words, if the input's name is not
prefixed with
ctl: or hdr:, then it will be
sent in the body of the generated message.
In addition to the above preprocessing of input variable names,
the values of all input variables are processed as follows:
- value substitution: If an input's value is prefixed with
val:input_name, then the value of the given
input will be the value of the input input_name.
As an example, suppose that there was a text input named summary
, which had been defined by the user of the form to be
"request info". If the hidden input hdr:subject
was defined to have the value "val:summary", then the
generated e-mail message would have the subject
"request info". Neat, huh?
- value concatentation: Multiple strings or input values can be
included in a single input by appending one string to another. The
plus character ('+') is used to split an input value into tokens,
and each token will be processed as any other input value (i.e. it will
be checked for a
val: prefix).
So, to continue the previous example, if the input hdr:subject
was defined to have the value "Form message: +
val:summary", then the generated e-mail message would have the
subject "Form summary: request info".
There is one caveat/bug here: a plus in an input (hidden,
typed, or otherwise) will probably end up being changed into a space.
This should be fixed in the next version of mailserf.
Predefined Input Variables
The following control inputs are defined by mailserf:
- ctl:required
- Description: The names of the inputs that must be defined before
the form can be submitted. The type of the inputs is somewhat arbitrary:
either hidden, text, or textarea will work. The one variable that must
always be defined, whether specified in this input or not, is hdr:to.
The input names should be provided as a comma-separated list.
See also: force_reqd
- ctl:required_url
- Description: URL to which the user's browser should be redirected
if all of the required fields aren't defined.
- ctl:required_mesg
- Description: Message to display if the user doesn't fill out a
required field. It is used only if ctl:required_url is not defined.
Default: "Sorry, but you must fill out all of the required fields
as indicated on the form."
- Appended Links
- The following ctl:link inputs describe the method by which
links can be appended to the followup message that is displayed after a
mailserf form is submitted. Each link directive is specified starting with
ctl:link#_, where # indicates the number of the link. The numbering of the links determines the order in which they are displayed at the end of
the followup page. The first link to be displayed should be numbered 1, and
each subsequent link should have the next higher integer number (i.e. 2, 3, 4,
etc). If any number is skipped, the links numbered above the skipped number
will be ignored.
- ctl:link#_url
- Description: The URL of the given link.
- ctl:link#_mesg
- Description: The text of the given link.
- ctl:link#_img
- Description: The image associated with the given link.
- ctl:link_sepstr
- Description: The string used to separate one link from another
at the end of the followup message. Conceptually, this could be an HTML
tag like
<hr>, although this hasn't been tested.
Default: "/"
- ctl:link_sepimg
- Description: Image used to separate one link from another.
- ctl:followup_url
- Description: The URL to display after a mailserf form has been
submitted. This URL will replace any output that would normally be generated
by mailserf.
- ctl:followup_head
- Description: The pathname of the file to prepend to the default
output from a mailserf form submission. The path should be relative to the
DOCUMENT_ROOT of the web server.
- ctl:followup_tail
- Description: The pathname of the file to append to the default
output from a mailserf form submission. The path should be relative to the
DOCUMENT_ROOT of the web server.
- ctl:pretty_print
- Description: Nicely format the mail body. Currently obsolete.
Default: True
- ctl:keep_empties
- Description: Include every body input in the generated e-mail
message, whether or not any value was defined for it.
Default: False
- hdr:to
- Description: The target address of the mail generated by mailserf.
It is required that this be defined.