Mailform script for AuroraCGI
The mailform cgi script is used to mail form data to
a particular address and simultaneously display a new page in the web browser.
This could also be done in JavaScript, but a cgi script does not have browser
dependencies, as JavaScript does.
Mailform inputs
Certain inputs appearing in the form control how mailform works. Actually,
they most likely will not "appear" in the sense of being visible -
you'll probably want to make them hidden - but they must exist in the form to
have any effect. (The markup of an example form is shown below.) The inputs
are:
- mf_mailto
- The e-mail address which will receive the form submission data. If an
error occurred while sending the mail, a message to that effect is
displayed, followed by the failure page.
- mf_mailfrom
- The e-mail address which will appear as the "From:" line of
the message. This can be used to make the mail message appear to come
from the person submitting the form by prompting for this information
in the body of the form. For instance:
<p>Enter your e-mail address:
<input type="text" name="mf_mailfrom"></p>
- mf_subject
- The subject to use in the mail message.
- mf_fields
- A list of the form field names, separated by spaces, that should be
included (with their values) in the mail message. See the note on
conditional field inclusion.
- mf_format
- A string used to format each line of the mail message. The default is
"%f: %v", which, for each value of
each field named in mf_fields, results in a line of the form
"field: value". The
"%" character is used to specify something to be
inserted in the line as follows:
- %%
- a literal percent sign.
- %f
- the input field name, as it appears in mf_fields.
- %u
- the field name, with underscores substituted for
characters that are not alphanumeric or
underscore.
- %v
- the field value.
- mf_reqfields
- A whitespace-delimited list of required form fields. If any of
these fields are left blank, no mail is sent, and the list of required
fields that were left blank is displayed, followed by the failure
page. See the note on conditional field
inclusion.
- mf_title
- Specifies the title of the new page. This will appear both between
<title>-</title> and
<h1>-</h1>.
- mf_headtags
- A string containing HTML tags to be included between
<head> and </head> in the
displayed page.
- mf_bodyattrib
- HTML attributes for the
<body> tag of the displayed
page.
- mf_success
- If this begins with a slash ("/") it is interpreted as a
filename, relative to your Aurora home directory, to display if all
required inputs were provided and mailing was successful. If it does
not begin with a slash, then the value of mf_success itself is
displayed in the new page. If the field is not present in the form, a
default value of "Success!" is used.
- mf_failure
- Displayed if required fields are missing, or if mailing
failed. mf_failure is interpreted the same as mf_success - slash
indicates a filename, anything else indicates the message itself.
- mf_maintainer
- The e-mail address that will be displayed (and linked to) in the
footer. If this field is not present, the value of mf_mailto is used.
Notes
- The mf_mailto and mf_fields inputs are required. If either of these is
absent, or present but without a value, an error message will be
presented directing the user to this documentation.
- Since the mf_fields and mf_reqfields lists are space-delimited, none of
the field names in them can contain spaces. However, you can use field
names containing spaces in the form and replace each space with an
underscore when that name is listed in mf_fields or mf_reqfields. Note
that because of how Aurora
makes form inputs available, fields named as, for example,
"field@" and "field#" cannot be distinguished, and
will both appear to have the value given for one of them.
- The title of the new page should not be respecified in mf_headtags. Use
the mf_title input to specify the title.
- When failure occurs, a message is always printed indicating the cause -
either missing required fields, or failure in sending mail. This is done
independently of (and appears above) the file or message specified in
mf_failure.
- The script generates the Aurora header and footer itself. The files or
text in mf_success and mf_failure should therefore not be complete html
pages; they should contain only content belonging between
<body> and </body>. A file used
this way, since it does not have the header and footer, cannot be used on
its own. It must be used exclusively for mailform (or other scripts that
also provide the header and footer).
- Fields can be conditionally included in mf_fields
and mf_reqfields. The simplest way to use this feature is to include
"foo=bar ? baz"
in mf_fields or mf_reqfields. This will include the baz field
in the output (or in the list of requried fields) only if the field
foo has the value "bar". Though conditions will
usually be like this example, they can get pretty complicated:
- foo=bar
- This is true if the field foo has the value
"bar". In the case of a multiple-select or checkbox,
the condition is true if any of the selected values is
"bar".
- foo
- This is true if the field foo is present in the form,
even if it has an empty value.
- cond1 cond2 &
- This is true if both conditions cond1 and cond2 are true.
- cond1 cond2 |
- This is true if either condition cond1 or cond2 is true.
- cond1 cond2 ^
- This is true if one of condition cond1 and cond2 is true and the
other is false.
- cond1 !
- This is true if condition cond1 is false.
A condition must be followed by a question mark surrounded by spaces
(" ? "), followed by the field(s) that depend on
this condition. A single field can apppear by itself after the question
mark; multiple fields depending on the same condition must be enclosed in
parentheses, also surrounded by spaces
(" ( field1 field2 ... ) ").
Instructions for use
To use this script, create the cgi/ and cgi/bin/ directories in your Aurora
home directory. Copy the script from
http://www.case.edu/help/AuroraCGI/mailform into your cgi/bin/ directory.
Any changes that need to be made for your particular needs, if any, can then be
made to your copy. An example form using mailform (for an account named
"Acct" maintained by abc123@case.edu):
<form method="post" action="/cgi-bin/AuroraCGI/Acct/mailform">
<input type="hidden" name="mf_title" value="Example Form Results">
<input type="hidden" name="mf_headtags" value='<base href="http://www.case.edu/Acct/">'>
<input type="hidden" name="mf_bodyattrib" value='bgcolor="silver"'>
<input type="hidden" name="mf_mailto" value="abc123@case.edu">
<input type="hidden" name="mf_subject" value="Example output">
<input type="hidden" name="mf_success" value="It worked!">
<input type="hidden" name="mf_failure" value="/stuff/failure.html">
<input type="hidden" name="mf_fields" value="foo bar">
<input type="hidden" name="mf_reqfields" value="foo">
Foo:<br>
<input type="text" name="foo"><br>
Bar:<br>
<input type="checkbox" name="bar" value="bar1">Bar1
<input type="checkbox" name="bar" value="bar2">Bar2
<input type="checkbox" name="bar" value="bar3">Bar3
<br><input type="submit">
</form>
Note: to test this form, you must replace "Acct" with your Aurora
APAS user id, and "abc123@case.edu" with your e-mail address. For help with
writing HTML forms, see the forms chapters
of the Intermediate HTML tutorial.
If the user entered "hello" in the foo field and checked the
first and third checkboxes of bar, the mail message would appear as:
foo: hello
bar: bar1
bar: bar3
If the user forgot to fill in the foo field, the page displayed
would appear as:
[Aurora header]
The following required field(s) were not entered: foo.
[Contents of the file failure.html, in your stuff/ directory]
[Aurora footer]
|
