Formmails
Home Services Issues & Themes News and Actions Support & Software Training About

 

Contents

  1. Introduction
  2. The FORM Action TAG
  3. The INPUT TAG
  4. The SELECT TAG
  5. The TEXTAREA TAG
  6. Putting it all together
  7. Creating A Form
  8. Optional Form Fields
  9. Some examples
1. Introduction

Formmail is an easy-to-use CGI program running on our Linux web server that sends the results of a submitted form as an email message. It can be used for many different types of form.

Don't be put off by the descriptions of the various TAGS and TYPES below. After the descriptions, there are a couple of working examples for you to cut and paste and test yourself. The most important parts are the FORM tag and the recipient field.

For those of you who are used to doing your own forms, you should find migrating to formmail syntax quite easy, there isn't much difference at all. For those of you who have never done a form, you might be suprised how easy it is.

2. Formmail TAGS

The FORM Tag

The FORM tag specifies the beginning and end of a mail-back form inside your HTML document. You can have more than one form within an HTML document, but you cannot 'nest' (that is - have a form within a form) forms inside your HTML document.

<FORM ACTION="url">
</FORM>
The Form Tag has several attributes , additional pieces of information that will tell GreenNet where our Formmail processor lives, and what to do with the data from your form. The attributes we are intrested in are:

action
and
method

You've probably seen them around!. The following line tells us where the formmail processor lives (http://www.yourdomain.org/cgi-bin/formmail.pl) and that we want to Post the results of the form to be sent to the server and processed according to our instructions.
NB: The 'cgi-bin' directory is a virtual directory which is linked to a central cgi-bin on the GreenNet server, it is not actually located in your web directory, so you won't see it when you connect to your site to upload files by FTP (this is the same with your 'logs' directory).

<form action="/cgi-bin/formmail.pl" method="post">

This line (above) is the first line you should have to indicate the beginning of a mailback form on GreenNet. If your form is located in a sub-directory of your site you may need to adjust the relative link, e.g. form action="../cgi-bin/formmail.pl"

 

THE INPUT TAG

As we've said above, you can have anything inside a form, except another FORM. In general we use the additional TAGS,

INPUT, SELECT, and TEXTAREA

to specify other interactive elements of the form.

The INPUT tag is used to specify a basic 'user input' element inside a form. It is a standalone tag and does not surround anything, nor does is have a 'terminating tag' -- i.e., it is used in much the same way as IMG. Here's an example of the use of an INPUT tag to create a simple text box, combined with our first 'FORM' tag above:

<FORM ACTION="cgi-bin/formmail.pl" method="post">

Enter your name here: <INPUT NAME="entry">

</FORM>

The INPUT tag has several attributes that define what type of input box you can have, what you want to call the contents of a field, what the default values are, how wide the boxes you see on the screen are.

TYPE where type can equal:

text   text entry field; this is the default
password   text entry field; entered characters are represented as asterisks
checkbox   a single toggle button; on or off
radio   a single toggle button; on or off
submit   a pushbutton that causes the current form to be packaged up and sent to a remote server
reset   a pushbutton that causes the various input elements in the form to be reset to their default values
hidden
  a field that contains important information for the server, but that you don't want people to see

NAME

NAME is the symbolic name of an input box. It must be present for all boxes except SUBMIT and RESET.

VALUE

When VALUE applies to text or password entry fields, it can be used to specify the default contents of the field. For a checkbox or a radio button, VALUE specifies the value of the button when it is checked (unchecked checkboxes are disregarded when submitting queries); the default value for a checkbox or radio button is "on". For types submit and reset, VALUE can be used to specify the label for the pushbutton.

CHECKED

Specifies that this checkbox or radio button is checked by default; this is only appropriate for checkboxes and radio buttons.

SIZE

SIZE is the width of the input field in characters; this is only appropriate for textentry fields and password entry fields. If this is not present, the default is 20 characters. Multiline text entry fields can be specified as SIZE=width,height; e.g. SIZE=60,12.

Note: the SIZE attribute should not be used to specify multiline text entry fields now that the TEXTAREA tag is available.

MAXLENGTH

MAXLENGTH is the maximum number of characters that are accepted as input. The SIZE type determines the width of a box as it appears on the screen, but you can use the MAXLENGTH type to turn the box into a 'scrolling' box - that is, by having your MAXLENGTH greater in width than your SIZE - but limited.

This is only appropriate for text entry fields and password entry fields (and only for single-line text entry fields at that). If you do not specify a MAXLENGTH, the default will be unlimited.

 

THE SELECT TAG

Like the INPUT TAG, several SELECT tags can be inserted freely between the

 

<FORM ACTION="url">
</FORM>
tags.

SELECT allows you to create a table of options that a user can literally select from. You may want to ask someone to give you their age range, and you offer a selection of ages to choose from. You may like to know what type of work area an organisation is involved in, say, environment, development, human rights etc - using the SELECT option, a user can select one or many different options (unlike the CHECK option with the INPUT TAG where an option is simply one thing or another (but not both).

Unlike the INPUT tag, the SELECT tag has opening and closing tags eg:

 

<SELECT NAME ="menu">
<OPTION> First Option
<OPTION> Second Option
</SELECT>

NAME

NAME is the symbolic name for this SELECT element. This must be present, as it is used when putting together the query string for the submitted form.

SIZE

if SIZE is 1 or if the SIZE attribute is missing, by default the SELECT will be represented as a Motif option menu. If SIZE is 2 or more, the SELECT will be represented as a Motif scrolled list; the value of SIZE then determines how many items will be visible.

MULTIPLE

MULTIPLE, if present (no value), specifies that the SELECT should allow multiple selections (n of many behavior). The presence of MULTIPLE forces the SELECT to be represented as a Motif scrolled list, regardless of the value of SIZE.

 

THE TEXTAREA TAG

The TEXTAREA tag can be used to place a multiline text entry field with optional default contents in a fill-out form. The attributes to TEXTAREA are as follows:

NAME is the symbolic name of the text entry field.

ROWS is the number of rows (vertical height in characters) of the text entry field.

COLS is the number of columns (horizontal width in characters) of the text entry field.

TEXTAREA fields automatically have scrollbars; any amount of text can be entered in them.

The TEXTAREA element requires both an opening and a closing tag. A TEXTAREA with no default contents looks like this:

<TEXTAREA NAME="organisation-type" ROWS=4 COLS=4>
</TEXTAREA>

A TEXTAREA with default contents would have the following ROW/COLUMN sizes:

<TEXTAREA="organisation-type" ROWS=4 COLS=40>
Default contents go here..
</TEXTAREA>

The default contents must be straight ASCII text. Newlines are respected (so in the above example there will be a newline both before and after "Default contents go here.").

 

PUTTING IT ALL TOGETHER

Now, let's put together a form demonstrating most of the above. We'll do a few forms, each one a little more complex than the last.

Let's just list the elements we have to work with:

HTML TAGS

<HTML>
<BODY>
</BODY>
</HTML>
FORM TAGS

<FORM ACTION="cgi-bin/formmail.pl" METHOD="POST">
</FORM>

INPUT TAGS

Enter your name here: <INPUT TYPE="text" NAME="yourname" SIZE="20">
Enter your password here: <INPUT TYPE="PASSWORD" NAME="Password" VALUE="Your password">
Click here if you got this far: <INPUT TYPE="CHECKBOX" NAME="Checkbox" VALUE="On">
Click here if you got this far: <INPUT TYPE="RADIO" NAME="Radio" VALUE="on">
<INPUT TYPE="SUBMIT" VALUE="Submit Form">
<INPUT TYPE="RESET" VALUE="Reset Form">

SELECT TAGS

<SELECT NAME ="orgtype" MULTIPLE>
<OPTION> Human Rights
<OPTION> Environment
<OPTION> Other
</SELECT>

TEXTAREA TAGS

<TEXTAREA ="yourcomment" ROWS=6 COLS=40>
</TEXTAREA>

and lastly .. SYSTEM TAGS

We haven't talked about system tags yet, but they are the tags that will go at the very beginning of the form, telling the server information it needs. There are INPUT TAGS, but their type is HIDDEN .

There are the main types you will need for your test form - they are all mainly concerned with the MAIL aspects of the formmail process. Who the mail should go to, who the mail should appear to be coming from, and the subject line for your mail message.

<input type="hidden" name="recipient" value="wwwadmin@gn.apc.org">
<input type="text" name="email">
<input type="text" name="subject" value="My Test Form">

NB: The recipient address must be a GreenNet address or the form will not submit properly, it will give you an error message. This means it must be an address at a domain name that we host, usually the same domain name as you use for your website. If you have problems with this contact wwwadmin@gn.apc.org for advice.

THE FORM

If all goes well, you should be able to cut and paste the following to create a form, which is also on GreenNet for testing, and looks like this.

Upload the form to your site and see if it works, it should!.. if it doesn't get back to me and let me know what went wrong.

Formmail has many more optional fields, for details on these click here.

1) Cut and paste between the <----- ------> marks into a plain text file and give it a .html extension.
2) Don't forget to put your real email address in the "recipients" INPUT tag, or you won't receive the results by email.
3) Upload the form to your site, bring up the URL and complete the form.
4) If you have followed the instuctions correctly, you should receive the form results back by email within a matter of seconds.
5) At the end of the cut and paste section are pointers to more advanced work on forms. GOOD LUCK!

<---------------------------------------------------------------------------------------------

<HTML>
<BODY>
<TITLE>My Test Form</TITLE>

<p> <strong><h3>My test form..</strong></h3>

<p> <FORM ACTION="cgi-bin/formmail.pl" METHOD="POST">

<input type="hidden" name="recipient" value="wwwadmin@gn.apc.org">
<input type="hidden" name="email" value="wwwadmin@gn.apc.org">
<input type="hidden" name="subject" value="My test Form">

<p> Enter your name here: <INPUT TYPE="text" NAME="yourname" SIZE="20">

<p> Enter your password here: <INPUT TYPE="PASSWORD" NAME="Password" VALUE="Your password">

<p> Click here if you got this far: <INPUT TYPE="CHECKBOX" NAME="Checkbox" VALUE="On">

<p> Click here if you got this far: <INPUT TYPE="RADIO" NAME="Radio" VALUE="on">

<p> What represents best the area of your organisation's work?: <SELECT NAME ="orgtype">
<OPTION> Human Rights
<OPTION> Environment
<OPTION> Other
</SELECT>

<p> Your Comments:<TEXTAREA ="yourcomment" ROWS=6 COLS=40>
</TEXTAREA>

<p> <INPUT TYPE="SUBMIT" VALUE="Submit Form">

<p> <INPUT TYPE="RESET" VALUE="Reset Form">

</FORM>
</BODY>
</HTML>

<---------------------------------------------------------------------------------------------

Optional Form Fields



Field:  subject
Description:  The subject field will allow you to specify the subject that you wish to appear in the e-mail that is sent to you after this form has been filled out. If you do not have this option turned on, then the script will default to a message subject: WWW Form Submission.
Syntax:  If you wish to choose what the subject is:
<input type=hidden name="subject" value="Your Subject">

To allow the user to choose a subject:
<input type=text name="subject">

Field:  email
Description:  This form field will allow the user to specify their return e-mail address. If you want to be able to return e-mail to your user, I strongly suggest that you include this form field and allow them to fill it in. This will be put into the From: field of the message you receive. If you want to require an email address with valid syntax, add this field name to the required field.
Syntax:  <input type=text name="email">

Field:  realname
Description:  The realname form field will allow the user to input their real name. This field is useful for identification purposes and will also be put into the From: line of your message header.
Syntax:  <input type=text name="realname">

Field:  redirect
Description:  If you wish to redirect the user to a different URL, rather than having them see the default response to the fill-out form, you can use this hidden variable to send them to a pre-made HTML page.
Syntax:  To choose the URL they will end up at:
<input type=hidden name="redirect" value="http://your.host.com/to/file.html">

To allow them to specify a URL they wish to travel to once the form is filled out:
<input type=text name="redirect">

Field:  required
Description:  You can now require for certain fields in your form to be filled in before the user can successfully submit the form. Simply place all field names that you want to be mandatory into this field. If the required fields are not filled in, the user will be notified of what they need to fill in, and a link back to the form they just submitted will be provided.

To use a customized error page, see missing_fields_redirect
Syntax:  If you want to require that they fill in the email and phone fields in your form, so that you can reach them once you have received the mail, use a syntax like:

<input type=hidden name="required" value="email,phone">

Field:  env_report
Description:  Allows you to have Environment variables included in the e-mail message you receive after a user has filled out your form. Useful if you wish to know what browser they were using, what domain they were coming from or any other attributes associated with environment variables. The following is a short list of valid environment variables that might be useful:

REMOTE_HOST Sends the hostname making the request.
REMOTE_ADDR Sends the IP address of the remote host making the request.
REMOTE_USER If server supports authentication and script is protected, this is the username they have authenticated as. (This is not usually set.)
HTTP_USER_AGENT  The browser the client is using to send the request.


There are others, but these are a few of the most useful. For more information on environment variables, see:
The CGI Resource Index: Documentation: Environment Variables
Syntax:  If you wanted to find the remote host and browser sending the request, you would put the following into your form:

<input type=hidden name="env_report" value="REMOTE_HOST,HTTP_USER_AGENT">

Field:  sort
Description:  This field allows you to choose the order in which you wish for your variables to appear in the e-mail that FormMail generates. You can choose to have the field sorted alphabetically or specify a set order in which you want the fields to appear in your mail message. By leaving this field out, the order will simply default to the order in which the browsers sends the information to the script (which is usually the exact same order as they appeared in the form.) When sorting by a set order of fields, you should include the phrase "order:" as the first part of your value for the sort field, and then follow that with the field names you want to be listed in the e-mail message, separated by commas. Version 1.6 allows a little more flexibility in the listing of ordered fields, in that you can include spaces and line breaks in the field without it messing up the sort. This is helpful when you have many form fields and need to insert a line wrap.
Syntax:  To sort alphabetically:
<input type=hidden name="sort" value="alphabetic">

To sort by a set field order:
<input type=hidden name="sort" value="order:name1,name2,etc...">

Field:  print_config
Description:  print_config allows you to specify which of the config variables you would like to have printed in your e-mail message. By default, no config fields are printed to your e-mail. This is because the important form fields, like email, subject, etc. are included in the header of the message. However some users have asked for this option so they can have these fields printed in the body of the message. The config fields that you wish to have printed should be in the value attribute of your input tag separated by commas.
Syntax:  If you want to print the email and subject fields in the body of your message, you would place the following form tag:

<input type=hidden name="print_config" value="email,subject">

Field:  print_blank_fields
Description:  print_blank_fields allows you to request that all form fields are printed in the return HTML, regardless of whether or not they were filled in. FormMail defaults to turning this off, so that unused form fields aren't e-mailed.
Syntax:  If you want to print all blank fields:

<input type=hidden name="print_blank_fields" value="1">

Field:  title
Description:  This form field allows you to specify the title and header that will appear on the resulting page if you do not specify a redirect URL.
Syntax:  If you wanted a title of 'Feedback Form Results':

<input type=hidden name="title" value="Feedback Form Results">

Field:  return_link_url
Description:  This field allows you to specify a URL that will appear, as return_link_title, on the following report page. This field will not be used if you have the redirect field set, but it is useful if you allow the user to receive the report on the following page, but want to offer them a way to get back to your main page.
Syntax:  <input type=hidden name="return_link_url" value="http://your.host.com/main.html">

Field:  return_link_title
Description:  This is the title that will be used to link the user back to the page you specify with return_link_url. The two fields will be shown on the resulting form page as:

  • return_link_title
  • Syntax:  <input type=hidden name="return_link_title" value="Back to Main Page">

    Field:  missing_fields_redirect
    Description:  This form field allows you to specify a URL that users will be redirected to if there are fields listed in the required form field that are not filled in. This is so you can customize an error page instead of displaying the default.
    Syntax:  <input type=hidden name="missing_fields_redirect" value="http://your.host.com/error.html">

    Field:  background
    Description:  This form field allow you to specify a background image that will appear if you do not have the redirect field set. This image will appear as the background to the form results page.
    Syntax:  <input type=hidden name="background" value="http://your.host.xxx/image.gif">

    Field:  bgcolor
    Description:  This form field allow you to specify a bgcolor for the form results page in much the way you specify a background image. This field should not be set if the redirect field is.
    Syntax:  For a background color of White:
    <input type=hidden name="bgcolor" value="#FFFFFF">

    Field:  text_color
    Description:  This field works in the same way as bgcolor, except that it will change the color of your text.
    Syntax:  For a text color of Black:
    <input type=hidden name="text_color" value="#000000">

    Field:  link_color
    Description:  Changes the color of links on the resulting page. Works in the same way as text_color. Should not be defined if redirect is.
    Syntax:  For a link color of Red:
    <input type=hidden name="link_color" value="#FF0000">

    Field:  vlink_color
    Description:  Changes the color of visited links on the resulting page. Works in the same way as link_color. Should not be set if redirect is.
    Syntax:  For a visited link color of Blue:
    <input type=hidden name="vlink_color" value="#0000FF">

    Field:  alink_color
    Description:  Changes the color of active links on the resulting page. Works in the same way as link_color. Should not be set if redirect is.
    Syntax:  For a active link color of Blue:
    <input type=hidden name="alink_color" value="#0000FF">

    Some Examples

    The following examples are derived from a Tutorial Run developed by NCSA (The National Center For Supercomputing Applications). Be careful though, the forms on this site are different from those at NCSA as NCSA use a different formmail programme. If you copy forms from the NCSA site they will not work on GreenNet, only those listed below.

    1. Example 1 -- a simple fill-out form.
    2. Example 2 -- three text entry fields.
    3. Example 3 -- text entry fields and checkboxes.
    4. Example 4 -- changing the default values of text entry fields and checkboxes.
    5. Example 5 -- changing various attributes of text entry fields.
    6. Example 6 -- multiple, independent forms in a single document.
    7. Example 7 -- radio buttons, "one of many" behavior.
    8. Example 8 -- password entry fields.
    9. Example 9 -- option menus.
    10. Example 10 -- scrolled lists with single and multiple selections.
    11. Example 11 -- multiline text entry areas.

    Some people complain that pressing Enter in a text field in Formmail causes the form to be submitted prematurely. The following bit of Javascript on text fields turns Enter into Tab.

    <INPUT TYPE="TEXT" name="whatever" size="25" onKeyDown="if(event.keyCode==13) event.keyCode=9;">

     

    Search Code of Practice Calendar Web E-mail Bulletin board Jobs & Volunteering
    GreenNet, Development House, 56-64 Leonard Street, London EC2A 4JX, Tel (UK): 0845 055 4011
    Tel (int'l): +44 (0)20 7065 0935 Fax: +44 (0)20 7253 2616
    Email: info@gn.apc.org