|
|
Config File Format
|
| |
|
|
| |
|
| |
|
|
|
Tagged Format
|
| |
The config file is defined by a set of tags, similar in spirit to HTML.
But the actual tags differ because the meaning is different.
If you leave most of the file blank, defaults will be assumed,
and your form will act very much as FormMail 1.0 did. But in
2.0 and 3.0, you can override these defaults to a large degree.
The tags are described below, but
you may (i.e. will) be interested in examples.
Don't worry, they're at the bottom, after the tag descriptions.
You might bring one up in a separate web window to compare it
to the tag descriptions below.
(For the technically interested, I invented a small tag set using
SGML, a meta-language for define tag sets. HTML is another such
example of an SGML-defined tag set. And since you already know
about how to specify HTML tags, the FormMail tags won't be too surprising.)
The SGML tags for the config file are of five general types.
| Initial tags | <!DOCTYPE>, <form> |
| Input tags | <validate>, <format> <auth> |
| Mail tags | <mail>, <to>, <cc>, <reply-to>, <subject>, <body> |
| File tags | <filename>, <dirname>, <body> |
| HTML response tags | <response> |
|
|
| |
|
|
|
Putting the form results into Mail, Files or HTML responses
|
| |
Before describing the tags in detail, you should be aware of how
to refer to the value of an HTML input field when setting up the tags.
Suppose you have an input field in your original HTML form:
<input name="myname" type="text" >
You may later refer to the value that the user types in as
$myname or ${myname}
In general, most everything in the config file starting with a dollar sign will be
interpreted as a field value. If you really want just a dollar
sign, escape it with a backslash: \$
You probably know that the quotes in the above <input>
tag are not necessary unless the values of name or type
have embedded spaces. Although it might be possible to use embedded spaces
in the name of an input field, don't try this unless you have very strong
proofreading abilities and/or like pain. If you do try this, make sure
to use the ${myname} format to refer to variables.
There are a few variables pre-defined for you, all of
which start with $fm_. In general, your variables
should be of the following form:
| $fm_date | current date |
| $fm_ip | name or ip address of client |
| $fm_all | a list of all form fields and values |
| $fm_form | name of your form (from the config file) |
| $fm_config | full path to the config file |
| $fm_referer | URL to the submitting HTML form |
| $fm_auth_bluestem_id | Bluestem id of submitter, if bluestem is used |
| $myname | value of the myname HTML input field |
| ${myname} | value of the myname HTML input field |
|
|
| |
|
|
|
The <!DOCTYPE> tag
|
| |
The first line of your config file must be:
<!DOCTYPE form SYSTEM 'FormMail-3.0.dtd'>
Don't worry about the details. This just tells the FormMail script
which version of the FormMail tag set that you've used.
I'll defined 'FormMail-3.0.dtd' to point to
'FormMail-3.x.x.dtd' as needed.
You can keep using 'FormMail-3.0.dtd' even
as the versions change within version 3.xx.
If I have to introduce any incompatible changes, I'll
increase the version level to 4.
|
|
| |
|
|
|
The <FORM> tag
|
| |
The config file contains a (possibly large) element in the form:
<FORM> ... </FORM>
and all the other tags will sit inside.
The <FORM> tag takes some attributes:
<FORM DEBUG NAME="form_name"> CONTACT="contact_email"
DEBUG |
Optional |
Just put in the word DEBUG.
This will prevent any mail from being sent, and will send lots of
diagnostics to your browser when you submit your form. Highly encouraged
for diagnosing why your form behaves as it does.
(Note that if your config file contains syntax errors, they are reported
to your web browser whether or not you have DEBUG turned on.
DEBUG is used to analyze the behavior of a syntactically-correct
config file that may or may not do what you want.)
|
NAME="form_name" |
Required |
Pick any form_name you want.
Best if different forms have different
names. You'll appreciate this when you have to deal with mail from
several different forms.
|
CONTACT="contact_email" |
Optional |
Email address to show user if an error occurs.
Default is the netid@uic.edu of the owner of the sgml file.
|
|
|
| |
|
|
|
The <FORMAT> tag
|
| |
The <format> tag lets you reformat some of the
input given by the user. This is useful for putting phone numbers in
standard format, or for removing non-numeric characters from what might
be a nominally numeric input field. The re-formatting completely
replaces each specified input field with a new value; the original
value is lost. If FormMail can't figure out what the improved format
should be, it leaves the original value alone. Note that
<format> does not do any input validation,
it just reformats. Also note that the reformatting action, when it
occurs, happens before any input validation implied by any
<validate> tags present.
The format of this tag is:
<FORMAT NAME="field_name" VTYPE="format_type" IF="if_cond">
NAME="field_name" |
Required |
field_name must match the name of an input field name
from the original HTML form. This is case-sensitive. |
VTYPE="format_type" |
Required |
format_type is the type of new format you require. |
IF="if_cond" |
Optional |
Format action will take place only if if_cond evaluates to true. |
The current acceptable values for VTYPE are:
| phone |
Tries to produce a 10 digit phone number, of the
form 312-996-1234. If 10 digits are specified,
they are reformatted. If 5 digits starting with 3, 5, or 6
are specified, or if 7 digits starting with a campus prefix,
it is assumed this is a UIC campus address
and is turned into 10 digits. Otherwise the value
is unchanged, but there may be some formatting to
put hyphens in the right places. |
| digits |
Non-numeric characters are stripped from the value. |
| email |
If an @ sign is present, the value is left alone.
Otherwise, @uic.edu is appended to the value. |
| netid |
Removes the string @uic.edu,
if present at the end of the field. |
| newline |
Replaces any newline in the string with a blank. |
|
|
| |
|
|
|
The <VALIDATE> tag
|
| |
You may want to establish some rules
for accepting user input. For example, there may not be any point
to accepting a submission unless an email or phone number is given.
Each validate tag sets up a rule for a given input field. If the
user violates any validate rule, he is told what the problem is,
and instructed to return to the form, correct the error, and re-submit
the form. (Those of you well-versed in javascript can probably
dispense with server-side validation, but the rest of us will find it handy.)
The format is:
<VALIDATE NAME="field_name"
PUBLIC="pub_name"
VTYPE="validation_type"
IF="if_cond">
NAME="field_name" |
Required |
field_name must match the name of an input field name
from the original HTML form. This is case-sensitive. |
PUBLIC="pub_name" |
Required |
pub_name is the public name, used to tell the user
which field had the input error. |
VTYPE="validation_type" |
Required |
validation_type is the type of validation you require. |
IF="if_cond" |
Optional |
Validation condition will be checked only if if_cond evaluates to true. |
The current acceptable values for VTYPE are:
| nonnull |
The field must not be blank. |
| netid |
The field must contain 3-8 alpha-numeric characters,
just like a UIC netid. No guarantee that it is a bona fide
neitd, and certainly no guarantee that it belongs to the client.
This would typically be used to identify someone at UIC, since every
real netid is owned by a single person. |
| email |
The field must look like an email address. Basically,
this is something like logname@machine.domain. If there
is no "@" sign, then "@uic.edu" is assumed.
Note that only the form of the address is checked. The
validity of the address is not checked.
This would typically be used if you wanted to send mail to
the client. The email address need not be one at UIC. |
| phone5 |
The field must contain 5 or more digits. It may
also contain other characters. |
| phone10 |
The field must contain 10 or more digits. It may
also contain other characters. |
| digits |
The field may only contain digits. |
|
|
| |
|
|
|
The <AUTH> tag
|
| |
The <AUTH> tag is used
to force the submitter to go through bluestem authentication,
so you may capture the authenticated netid. I don't recommend this
for sending email, because email is itself not secure, and it's
hard to ensure that any email you receive was truly sent from FormMail.
However, this tag will enforce the use of bluestem, so if you write
the information to disk, and the security on the files are acceptable,
you have reasonable assurance that the submitter did use the appropriate
password when authenticating. (Of course, there are occasions where a password
is lent or stolen, but that's beyond the scope of formmail or bluestem.)
The format is simply:
<AUTH VTYPE=bluestem>
Note you must adjust the ACTION attribute in the FORM
tag as well, for bluestem to be used within FormMail.
|
|
| |
|
|
|
The <MAIL> tag
|
| |
Each <MAIL> ... </MAIL> set describes
a note that will be sent when the HTML form is filled out and
submitted. You may have more than one note (in case they have
different formats) and each note may be sent to multiple recipients.
The format is:
<MAIL NAME="mname" NOMAIL IF="if_cond">
The attributes are:
NAME="mname" |
Optional |
mname is used to identify the mail section for debugging. |
NOMAIL |
Optional |
If used, no mail from this section will be sent. Used for
debugging. Also, if you do not want any mail sent,
then you must have at least one <mail>
section with the NOMAIL attribute turned on. |
IF="if_cond" |
Optional |
Mail will be sent only if if_cond evaluates to true.
(NOMAIL option will override, if present.) |
Inside each <mail> ... </mail> section,
there are several other allowed tags:
<To> ... </To> |
Optional |
Multiple tags |
One tag per email address.
Default: is the netid of the owner of the config file. |
<Cc> ... </Cc> |
Optional |
Multiple tags |
One tag per email address. No default. |
<Reply-To> ... </Reply-To> |
Optional |
Single tag |
Sets Reply-To header on mail. Specify the email address
of the person filling out the form, or perhaps your email
address on mail sent to others. No default. |
<From> ... </From> |
Optional |
Single tag |
Sets From header on mail. Normally best to leave alone,
and rely on the Reply-To field.
But if you have to set it, you can. Sometimes
useful if the mail will be sent to an automatic program
like listserv. Default: web_mailer@uic.edu.
|
<Subject> ... </Subject> |
Optional |
Single tag |
Defaults to form_name submission, where form_name
is the name of the form from the config file. |
<Body> ... </Body> |
Optional |
Single tag |
Specify the body of the note.
Defaults to the list of all filled in fields. |
Note: If you specify multiple fields where only one is allowed
(e.g. <Subject> ), no error message will
be generated, but only the last tag will be used.
In addition, the mail will automatically contain the following headers:
- X-netid: netid where netid is the
netid of the owner of the config file.
- X-fm_form: form_name path
where form_name is the name of the form from the config file,
and path is the full path to the config file.
When mail is sent
If no <MAIL> sections are specified,
or if all the specified sections have if_conds that
evaluate to null, then a default
note is generated, and sent to the netid@uic.edu owner of
the config file, using the default body.
But if the only specified mail sections have the nomail
attribute set, then no mail is sent, whatsoever.
In other words, you have a very flexible ability to adjust who gets
what notes. If it seems that you wanted to send a note, but for
some reason all conditions evaluate to null, then a default note is
sent just to be sure information is not lost. And if no mail sections
are specified, the default note is sent, so as to emulate the
behavior of FormMail 1.0.
On the other hand, if it is clear you
don't want any mail (by specifying NOMAIL on all mail sections)
then you don't get any.
This lets you use FormMail solely for its ability to generate custom
HTML responses, without filling your inbox.
|
|
| |
|
|
|
The <FILE> tag
|
| |
Each <FILE> ... </FILE> set describes
a note that will be written to disk when the form is
submitted. You may write (or append to) more than one file
(perhaps with different formats) if you have multiple FILE sections.
The format is:
<FILE NAME="mname" NOFILE IF="if_cond">
The attributes are:
NAME="mname" |
Optional |
mname is used to identify the file section for debugging. |
NOFILE |
Optional |
If used, no information is written to disk. Used for
debugging.
|
IF="if_cond" |
Optional |
File will be written only if if_cond evaluates to true.
(NOFILE option will override, if present.) |
Inside each <file> ... </file> section,
there are several other allowed tags:
<Filename> ... </Filename> |
Optional |
Multiple tags |
One tag per file that you will append to.
No default. Be sure this file is writable by the
owner or group of the sgml config file. |
<Dirname> ... </Dirname> |
Optional |
Multiple tags |
One tag per directory. No default.
A new file (of random name) will be written to this directory
upon form submission. Be sure this directory
already exists and is writable by either the owner or group
of the sgml config file.
|
| |
<Dirname Filebase='myprefix'> ... </Dirname>
Filebase is an optional attribute, to specify the beginning
part of the random filenames written to the directory.
|
<Body> ... </Body> |
Optional |
Single tag |
Specify the text written to file.
Defaults to the list of all filled in fields. |
Note: If you specify multiple fields where only one is allowed
(e.g. <Body> ), no error message will
be generated, but only the last tag will be used.
When files are Written
You can write to a file when you specify a <FILE>
section with either Filename (for appending to a given file)
or Dirname (for creating a new file). You must also
have any if_cond evaluate to true, and not
have the NOFILE option.
Note that FormMail is oriented towards sending mail. If you want to
write to disk and not send any mail at all, you still must include
a <MAIL NOMAIL> section to block the sending of mail.
Also note that writing files is a bit more problematic than sending
mail. Questions of write permissions and disk quotas can cause
problems. If the write does not happen, FormMail will try to notify
the user.
When Errors are Generated
If one or more <FILE> sections are supposed to write
files, and at least one of them succeeds in writing the file,
no error is generated. But if all of them fail, then an
error is shown to the user.
That means, if you have multiple sections for writing files,
and something is wrong with one of them, the user will not
see any error, since the info is saved to disk somewhere.
|
|
| |
|
|
|
The <RESPONSE> tag
|
| |
The <RESPONSE> ... </RESPONSE> sections
control the HTML generated in response to the filled out form.
There may be many such sections, and they are evaluated in the order
presented in the config file. The syntax is:
<RESPONSE NAME="mname" IF="if_cond" URL="url">
The attributes are:
NAME="mname" |
Optional |
mname is
used to identify the response section for debugging. |
IF="if_cond" |
Optional |
Response will be
printed only if if_cond evaluates to true. |
URL="url" |
Optional |
Output will be
redirected to the given full url. Do not use a relative
url, make sure it
starts with http or ftp or other valid protocol.
No check for validity of the redirected
url is made. No other response sections will be evaluated if
the redirection is made. |
The sections are evaluated in order. If the first to evaluate to
true contains a URL redirection, the output is redirected.
Otherwise, all sections that evaluate to true are
sent back to the client browser.
The body of a <RESPONSE> section should contain
the HTML code to print. HOWEVER, the enclosed HTML tags must be
protected from the SGML parser for this to work. This means that
a response section should look like:
<RESPONSE NAME="resp1">
<![CDATA[
here is some <b>HTML</b> code
]]>
</RESPONSE>
Important Note: If you choose to use the
<RESPONSE> tags to generate any part
of the HTML response, you are entirely responsible
for generating the whole response page, from the
beginning <html> tag to the ending
</html> tag. Don't presume that
FormMail will do any of this for you, unless
one of the following is true:
- You omit the
<RESPONSE> tags,
and let FormMail generate its default response.
- You use URL redirection within the
<RESPONSE> tag.
|
|
| |
|
|
|
The "if_cond" conditions
for various tags
|
| |
The optional if conditions specified in the
<FORMAT>,
<VALIDATE>,
<MAIL>
and <RESPONSE>
sections are expressions separated by Boolean ANDs and ORs.
But the conditions are not totally general, because parentheses
are not allowed, and the ANDs bind tighter than the ORs.
Therefore
exp1 AND exp2 OR exp3 OR exp4 AND exp5
is parsed as:
(exp1 AND exp2) OR (exp3) OR (exp4 AND exp5)
I hope this is sufficient for most needs.
Each expression is evaluated as a string comparison or numeric
comparison, depending on the operator used.
Each expression should take one of the following forms.
Note that each comparison operator must be delimited with blanks.
| Expression | True if: | Type |
|---|
| string |
string evaluates to non-null |
string |
| NOT string |
string evaluates to null |
string |
| string1 eq string2 |
string1 equals string2 |
string |
| string1 ne string2 |
string1 does not equal string2 |
string |
| string1 pre string2 |
string1 begins with string2 |
string |
| string1 npre string2 |
string1 does not begin with string2 |
string |
| num1 == num2 |
num1 equals num2 |
numeric |
| num1 != num2 |
num1 does not equal num2 |
numeric |
| num1 >= num2 |
num1 is greater than or equal to num2 |
numeric |
| num1 <= num2 |
num1 is less than or equal to num2 |
numeric |
| num1 > num2 |
num1 is greater than num2 |
numeric |
| num1 < num2 |
num1 is less than num2 |
numeric |
where string is either a hard-coded string (case-sensitive),
or a dollar-variable, such as $var or $fm_name. The string
should not contain internal blanks.
For numeric comparisons, num should evaluate to a number,
where null evaluates to 0.
Using numeric comparisons with non-numeric strings
is undefined, and should not be relied on to produce
either true or false.
|
|
