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. Please note that on new sites this program isn't automatically enabled, so if you want to use it please contact us and we can turn it on for you.
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.
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.
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
methodYou'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).
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:
Enter your name here:
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
| 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
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:
First Option
Second Option
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:
A TEXTAREA with default contents would have the following ROW/COLUMN sizes:
Default contents go here..
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
FORM TAGS
INPUT TAGS
Enter your name here:
Enter your password here:
Click here if you got this far:
Click here if you got this far:
SELECT TAGS
Human Rights
Environment
Other
TEXTAREA 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.
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.
- Cut and paste between the <----- ------> marks into a plain text file
and give it a .html extension. - Don't forget to put your real email address in the "recipients"
INPUT tag, or you won't receive the results by email. - Upload the form to your site, bring up the URL and complete the form.
- If you have followed the instuctions correctly, you should receive the
form results back by email within a matter of seconds. - At the end of the cut and paste section are pointers to more advanced work
on forms. GOOD LUCK!
My Test Form
My
test form..METHOD="POST">
Enter
your name here:
Enter your password here:Click here if you got this far: NAME="Checkbox" VALUE="On">
Click here if you got this far: TYPE="RADIO" NAME="Radio" VALUE="on">
What represents best the
area of your organisation's work?:
Human Rights
Environment
OtherYour Comments:
| 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: To allow the user to choose a subject: |
||||||||
|
|
|||||||||
| Field: | |||||||||
| 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: | |||||||||
|
|
|||||||||
| 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: | |||||||||
|
|
|||||||||
| 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: To allow them to specify a URL they wish to travel to once the form is filled out: |
||||||||
|
|
|||||||||
| 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: |
||||||||
|
|
|||||||||
| 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:
|
||||||||
| Syntax: | If you wanted to find the remote host and browser sending the request, you would put the following into your form: |
||||||||
|
|
|||||||||
| 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: To sort by a set field order: |
||||||||
|
|
|||||||||
| 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: |
||||||||
|
|
|||||||||
| 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: |
||||||||
|
|
|||||||||
| 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': |
||||||||
|
|
|||||||||
| 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: | |||||||||
|
|
|||||||||
| 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: |
||||||||
| Syntax: | |||||||||
|
|
|||||||||
| 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: | |||||||||
|
|
|||||||||
| 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: | |||||||||
|
|
|||||||||
| 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: |
||||||||
|
|
|||||||||
| 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: |
||||||||
|
|
|||||||||
| 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: |
||||||||
|
|
|||||||||
| 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: |
||||||||
|
|
|||||||||
| 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: |
||||||||