HTML Forms: Using WebMail

HTML Forms: Using WebMail

WebMail is a special program which takes a user's input from a Web page and generates an email message containing the data.

How do I use it?

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 can't send to just anyone. Please use this form to set up a recipient list.

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.