HTML Forms: Using WebMail
How do I use WebMail?
You create an HTML form that contains certain special input fields
that tell WebMail what to do.
You tell your form to call WebMail when the user submits the information.
WebMail sends the contents of the submitted form to one or more
recipients, who you specify.
Important: you must set
up a recipient list, you can't send a Webmail to just anyone.
HTML Code
| The Form
Creation Wizard is a good way to create the necessary hidden
fields, without having to know too much about HTML code. It
asks you a series of questions and generates code that you can
copy and paste into your web page. |
If you need information about creating FORMs with HTML, we can
recommend two references. For people who are starting out, you might
like a tutorial.
If you want a succinct summary of the different tags, try the HTML
2.0 specification.
WebMail is invoked as the ACTION for your form in
the standard way: <form method=post action="/cgi/WebMail">.
Note that WebMail requires that you use the POST method.
All of the information passed to WebMail is passed as input fields.
You have complete discretion as to the method of creating the information:
You may submit the information yourself as hidden elements, or you
can have the user enter information. Required Fields
Certain fields are required for WebMail to function properly.
If a form is submitted to WebMail without one of these fields, WebMail
generates an error message and displays it to the user. No information
will be sent to the recipient.
|
Field Name |
What it Does |
| to_nickname
|
This is
the nickname of the WebMail recipient(s) who will receive the
information from the form. WebMail recipients must be registered
with the WebMaster before they can begin receiving messages
from WebMail. Nicknames will typically be MHC usernames for
single recipients (e. g. dwilga) or a mnemonic
for a group (e. g. libref for the library reference
desk). To see what the output would look like without sending
any email, use the value test. |
| from_name
|
This is
the real name of the person sending the form. WebMail uses this
information in the mail header so that the recipient will know
who the mail came from. This value is usually entered by the
user submitting the form. |
| from_address
|
This is
the email address of the person sending the form. WebMail uses
this information in the mail header so that the recipient will
be able to reply to the message. This value is usually entered
by the user submitting the form. |
| subject
|
This is
the subject of the message. In free-form messages, it's best
to let the user enter the subject. However, for many standard
forms, you can use a standard subject line and make it a hidden
input so the user can't change it. |
| message
|
This is
the body of the message. In free-form messages, it's best to
let the user enter the message. However, for many standard forms,
you can use a standard message (e.g. Please renew the
following book that I have checked out:) and make it
hidden so that the user can't change it. |
Additional Fields
You can add any additional fields that you like to contain the
information in your form. Be sure to assign each item its own name
(with the exception of radio buttons, which are grouped under the
same name). You can have WebMail print the contents of any or all
of these extra fields at the bottom of your message.
The following list consists of other optional fields that you can
use to control WebMail's behavior.
| Field
Name |
What
It Does |
| field_required |
Use this
field to make some of your own fields required. If the user
doesn't fill them in, WebMail will return an error message telling
him or her which fields are missing. The value of this field
should be a list of field names, each enclosed in {curly
braces}. For example, if I have two that I want
to make required, called "city"and "state",
I could enter <input type=hidden name
"field_required" value="{city}{state}">. By
default, the error message that the user sees if a required
value is left blank contains the exact name of the field. Depending
on how the field was named, this may not provide a very good
description for the user. In this case, you can use the format
{fieldname=Long Name}. This way, the error message
will show the Long Name of the field, which will
hopefully give them a better idea which field to fill-in. For
example:
<input type=hidden name "field_required"
value= "{city=The City were you live}
{state=Your State}"> |
| field_order |
Use this
field to tell WebMail to list your own fields at the bottom
of the message. If you create your own fields and want them
to display, you must include a field_order field.
The value of the field should be a space-separated list of field
names in the order in which you want them to be listed. You
may use any valid field name, whether it is a standard field
or one of your own. For example,
<input type=hidden name="field_order" value="from_name from_address
city state"> |
| from_info |
Set the
value of this field to anything ("yes" is a good
choice) and WebMail will report back to you the Internet address
and browser used by the person sending the message. |
| keep_eols |
Set the
value of this field to anything ("yes" is a good
choice) and WebMail will not convert the end-of-line characters
that are sent as part of text fields into spaces. This has the
advantage that you will see things exactly as the user typed
them, particularly in textboxes. It has the disadvantage, however,
that your email program may try to impose its own idea of where
the linebreaks should be, thus defeating the purpose. |
| assume_MHC |
Set the
value of this field to anything ("yes" is a good
choice) and when WebMail receives a from_address
without a host name, it will assume that the string @mtholyoke.edu
should be tacked onto the end. This option should only be used
for forms that are targeted at the MHC community, since doing
this for a non-MHC address would lead to an incorrect email
address. In this case, it is far better that the user get the
standard error message telling her to correct the address. |
| verify_MHC_user |
Set the
value of this field to anything ("yes" is a good
choice) and WebMail will attempt to confirm that the e-mail
address given in from_address belongs to a user
at MHC. This is very easy for someone to fake, but is a way
to check identities and also for screening for cases when users
type in their own email address incorrectly. This option automatically
turns on the from_info option. |
| no_log |
Normally,
WebMail logs all data users submit, in a location that can only
be read by system administrators. Set the value of this field
to anything ("yes" is a good choice) and WebMail
will log only very minimal information about what happens when
the user submits a form. Use this option at your own risk.
If you accidentally delete the email, or if an error occurs
when the web server tries to send it to you, the data submitted
by the user will be permanently lost. |
| return_URI
|
WebMail
posts a receipt to the sender that contains a "Return"
button. This button normally points to the original form. If
you would like the "Return" button to point to something
else, use this tag. The value is the URL of the place the button
should go. For example, <input type=hidden
name="return_URI" value="http://www.mtholyoke.edu">. |
| send_MIME
|
Set the
value of this field to anything ("yes" is a good
choice) and WebMail will send the email message in a two-part
MIME format, with the data appearing in the second part. This
makes it easier to print just the data on a sheet of paper,
without all of the email header information. To access this
"part" by itself within Pine, press "V"
to View attachments, then choose part #2. |
| receipt_page
|
If this
field is set to the name of an HTML (or SHTML) file in the same
directory as the page containing the form, that page is displayed
instead of the default confirmation page. This allows you to
create a custom confirmation page. To
include the standard results within the custom confirmation
page, place the comment <!--%%PREVIEW%%-->
at the location where you want them to appear.
Note:
If your receipt page has any images or links to other pages
in it, they must be absolute URLs. This is because at the
time your page is being displayed the "working directory"
of the URL is that of /cgi/WebMail.cgi.
For instance,
if the receipt page was stored in /offices/reg/thankyou.html
and wanted to refer to an image in that same folder, it should
use a URL like /offices/reg/someimage.gif. If
this is left as just someimage.gif, the Web browser
will try to load /cgi/someimage.gif, which does
not exist. |
Example
Here's an example of a form that uses WebMail to find out some
information about the reader:
<form method=post action="/cgi/WebMail">
<input type=hidden name="to_nickname"
value="test">
<input type=hidden name="subject"
value="User Status">
<input type=hidden name="message"
value="Please record the information below.">
<input type=hidden name="field_order"
value="from_name Race">
<input type=hidden name="field_required"
value="{from_name=Your name}{Race}">
Your name: <input name="from_name" size=45><p>
Your email address:
<input name="from_address" size=45><p>
Your race:
<select name="Race">
<option value="">(Choose One)</option>
<option value="weakling">Human</option>
<option value="warrior">Klingon</option>
<option value="fascist">Romulan</option>
<option value="mercenary">Farengi</option>
<option value="communist">Borg</option>
</select><p>
<input type=submit value="Submit Information">
</form>
WebMail normally sends email to the list of users whose addresses
are associated with the "to_nickname" you supply. However, this
example uses the value "test", which instead causes the output to
go to the screen and does not send any email.
To see what this form produces, fill-in some information and click
on the Submit Information button. |
