A Guide to HTML

7.1. Setting up the form

Forms consist of start and end FORM tags: <form></form>

<form method=POST action="http://users.ox.ac.uk/cgi-bin/FormMail.pl" />

Two form fields are required when creating your feedback html form, namely a recipient field, and an email field. The former is a hidden field (this is not displayed to the user) and is the first to be received by the script and must contain your valid University email address:

<input type="hidden" name="recipient" value="example.user@unit.ox.ac.uk" />

Using "recipient" in the name attribute of this field is important, and you must give it a value using the value attribute. This is where you put your University email address, which the form data is later sent to.

The second required form field is the email field. It can be added to the form in two ways: either as a "hidden" field, in which case you should provide your University email address as the field's "value"; or as a normal form field, in which case the person submitting feedback is required to enter their email address. For example:

<input type="hidden" name="email" value="example.user@unit.ox.ac.uk" />

Would set the "From" address of the final email to be from your University email address (if it is "example.user@unit.ox.ac.uk"). Whereas using:

<input type="text" name="email" />

in the form would require the user submitting feedback to enter their address for use as the message's "From" address.

Note: If your form has two email fields, only the first will apply.

There are many other "hidden" fields that are available, two of which will likely be of regular use, namely subject and redirect. The former provides the text that will be used as the subject header of the email message delivered to you. If left out, the email message will have a generic subject header. If the latter field, redirect, is present, it should contain a valid HTTP URL, to which the user will be redirected after successful submission of the message.

Other hidden fields can control various configuration aspects of your form. Below is a brief list of the more useful fields.

return_link_url

If you're not using an immediate redirect, as mentioned above, return_link_url will enable the default success page to provide a link to the target URL. This is normally used to provide a link from the success page back to your main page or back to the page with the form on. For example:

<input type="hidden" name="return_link_url" value="/home.html" />

return_link_title

The label for the return link. For example:

<input type="hidden" name="return_link_title" value="Back to my home page" />

bgcolor

The background color for the success page.

background

The URL of the background image for the success page.

text_color

The text color for the success page.

link_color

The link color for the success page.

vlink_color

The vlink color for the success page.

alink_color

The alink color for the success page.

title

The title for the success page.

sort

This sets the order in which the submitted form inputs will appear in the email and on the success page. It can be the string alphabetic for alphabetic order, or the string order: followed by a comma separated list of the input names, for example:

<input type="hidden" name="sort" value="order:name,email,age,comments" />

If order: is used you must supply the names of all of the fields that you want to be in the body of the mail message.

env_report

This is a list of the CGI environment variables that you would like to be included in the email. For more details, see the section regarding validation below.

print_blank_fields

If this is set to a non-empty value then fields that the user left blank will be included in the email, for example:

<input type="hidden" name="print_blank_fields" value="true" />

Normally, blank fields are suppressed to save space.

You can view an example form for use on your site. To save this file right click on the mouse button and select [save as]. Please rename the file as .html when incorporating into your site.

7.2. Form validation

You can configure form mail to require certain fields to be completed. To enable the checking of required fields, use the the required hidden form field, this is a list of fields that the user must fill in before they submit the form. If they leave any of these fields blank then they will be sent back to the form to try again. For example:

<input type="hidden" name="required" value="name,comments" />

would require the name and comments form fields to be non-empty. If you want finer control over the the error that the user see's if they miss out a field you can add another hidden field, namely missing_fields_redirect. This field must have a valid URL as its value attribute, and the user will be redirected there if any of the fields listed in required are left blank.

Note: email is implicitly required, and does not need to be included in your own list of required fields.

If you would like the email returned to you to contain certain information about the remote host, browser agent, and referring host that used the form (and possibly some user information, if known), then you can include the env_report hidden form field, which lists the variables you would like included (as long as those variables are supported by the FormMail.pl script). For example:

<input type="hidden" name="env_report" value="REMOTE_HOST,REMOTE_ADDR,REMOTE_USER,HTTP_USER_AGENT,HTTP_REFERER" />

would provide a selection of potentially useful information (although not all variables are guaranteed to be present). What you do with the data from there is up to you!