Web Services - Form Mail
Thursday April 18, 2024 - 17:58:55
Orpheus Internet Services Ltd

Orpheus Form Mail

This script will allow you to add forms to your webpages, so that visitors can enter information that will be emailed to you automatically when they click a submit button.

A range of parameters allows quite flexible control over how the form behaves.

A list of the parameters needed to run the script appears below; however, some users have requested more of a tutorial on how to create mail forms.


Full list of parameters

mailto     Orpheus POP box to send resulting data to - this script is restricted to use by Orpheus subscribers, so you need to ensure that this is a valid POP box identifier, eg. ab15
mailfrom     email address of the sender - you usually get the user to type this into a text box. If this is not set or filled in, the From: header of the email you receive will be from null.user@orpheusmail.co.uk, replies to which disappear into a sort of black hole so that nobody gets flooded with replies to incorrectly filled out scripts (which is very likely to happen if you use an automated response program).
mailsubject    subject of the email
linkto     Web page that is shown once the user has submitted the data
browserdetails    set to 'yes' to provide additional details of the remote web browser
Key:
    compulsory
    highly recommended


The Basics

A form looks something like this...

Enter something:

|


<form>
  Enter something:<br>
  <input type="text" name="parameter" size="32">
  <p align="center">
    <input type="submit"> |
    <input type="reset">
  </p>
</form>

You're encasing the block of HTML to do the form in a <form>...</form> structure, in much the same way as, for instance, a table structure - you define the area of the form, and then put the actual controls that displays stuff inside this, which means you can have more than one form on a page and each form will know what buttons etc. belongs to it.

This example form also has some other fairly common, but by no means compulsory, elements in it. These are the text box - a simple one-line text entry area - created using <input type="text" name="parameter" size="32">, and then there's the two buttons, one to submit the form data to whatever controlling program is running on a web server waiting to receive this data, and another to wipe clean any data you might have entered so that you can start again. These are created using <input type="submit"> and <input type="reset">.

See the pattern emerging? Most controls in forms are via
<input type="something">
More on that later.


Creating the mail form
<form...>...</form>

All form data gets sent to a program running on a computer somewhere - usually a program in a directory called cgi-bin on the same server your webpages are uploaded to. CGI stands (in this case) for Common Gateway Interface, which basically means a standard way of sending data to a web-based program (also known as a "script").

The program we're using is located at /cgi-bin/formmail, and to tell the Web browser to us this program you need the following command:
<form method="get" action="/cgi-bin/formmail">


Hidden commands
<input type="hidden"...>

To set up the mail form, there are certain command which have to be passed to the CGI script, to tell it who you are and how you want it to work. Although you can pass all of these using text boxes, there's really no need for the user to see these, or indeed be able to edit them. This is where hidden inputs come in:
<input type="hidden" name="mailto" value="ab15">

With this form, you will probably want to use the following as hidden inputs:

Name Example
mailto <input type="hidden" name="mailto" value="ab15">
mailsubject <input type="hidden" name="mailsubject" value="Message from web page">
linkto <input type="hidden" name="linkto" value="http://yoursite.orpheusweb.co.uk/index.html">
browserdetails<input type="hidden" name="browserdetails" value="yes">
You will probably want to do the mailfrom part as a text box so the user can enter their own address....

Browser details

If you use the browserdetails hidden parameter, the formmail script will include additional information about the users web browser. This can be useful for diagnostic checking or webstats.

Single line text boxes
<input type="text"...>

These boxes are probably the most commonly used type of form input - they allow the user to type in a short piece of text, such as their name, email address, street name and so on.

<input type="text" name="mailfrom">

The name section can be anything - if it's not one of the options the script recognises then it will be put into the email, so...
<input type="text" name="my_name">
...will result in something like this showing up in the email you receive:
my_name
"Fred Smith"

You can enter some text automatically by using the value="..." attribute:
<input type="text" name="mailfrom" value="@orpheusmail.co.uk">

You can set the size of the box on screen by using the size=".." attribute, and set the maximum number of characters that can be entered by using maxlength=".." - for instance, size="32" maxlength="64" (note that they don't have to be the same!)


Multiple line text areas
<textarea>...</textarea>

For larger text boxes, the rules change a little - you use <textarea>...</textarea> tags, with the default text in between the tags.

You can set the height and width using rows="5" and cols="32"; there are also a few different ways of set how text wraps inside the box, the main two being: wrap="virtual"|"physical"> - virtual just wraps while the user is typing, whereas physical means that the text that is received at the other end is formatted in the same way.

Example:

<textarea name="message" rows="5" cols="32" wrap="virtual">
 Some default text
</textarea>


Tick boxes and radio icons
<input type="checkbox"|"radio">

Tick (or "check") boxes and radio icons are very similar - the user clicks on them to select or deselect them, and any selected items are listed in the email you receive at the other end. You can have any number of tick boxes, all of which should have a different name to differentiate them; radio icons, however, are for multiple choice questions where selected one icon with the same name unselects any others with the same name. If you want to have more than one group of radio icons, just give the second set a different name.

You can change the value that is sent through by using the value="..." attribute - vital for radio icons to tell one from the other, but for tick boxes perhaps you can use it to give it an easier-to-read value (usually it returns either "on" or doesn't appear at all if switched off); and you can select an icon by default simply by adding checked (with no extra parameters)

Examples:

Untick this box if you do not want to be added to our mailing list
<input type="checkbox" name="maillist" checked>
 Untick this box if you do not
 want to be added to our mailing list

Decision time:
Yes
No
Maybe

Decision time:
<br>
<input type="radio" name="decision" value="yes" checked>
  Yes
<br>
<input type="radio" name="decision" value="no">;
  No
<br>
<input type="radio" name="decision" value="maybe">
  Maybe

Menus
<select...><option>...</select>

You can create menus by nesting <option...> tags inside a <select..></select> pair. This is quite easy to show in operation as that is what is used to do the list of links to other sections of this site at the top of the page!

The opening <select...> tag should have a name="..." to identify it; you can also add multiple (with no extra parameters) so that more than one option can be selected in the list. Some computers also allow you to add size=".." so that a box with more than one line is shown - instead of using a separate menu to select an option, the user can select from one (or more) of the options displayed inside the box.

Options are added using the <option> tag. These tags are immediately followed by the plain text which is used as that option's display in the menu. This text is returned in the email as the value of this selection, unless you define another piece of text using the value="..." attribute. Finally, as with other tags you can add selected (with no extra parameters) to choose an option other than the first in the list to be the default.


Buttons
<input type="submit"|"reset">

There are basically two buttons you should be aware of - a submit button in the form of a <input type="submit"> tag will probably be needed on all forms to send the data off (although you can use images instead - see below), and it's usually nice to have <input type="reset"> so that the user has a way of resetting the form back to the default values in one easy step.

Both of these can have the text displayed on the button changed by using the value="..." attribute. For instance:

You can or you can
You can
<input type="submit" value="send this">
or you can
<input type="reset" value="wipe it clean">

Images
<input type="image"...>

You can also use an image instead of a submit button; its attributes should be familiar to those of you who have used the <img...> tag with its attributes.

The main attribute you need is to tell the browser where to get the image from; as with the <img...> tag this is done using the src="..." attribute. You can also include width=".." and height=".." tags to tell the browser how big the image will be before it is downloaded. One change however is that to change the text displayed if the image can't load, you don't use the alt="..." attribute; here it is value="..." instead.

However, by using an image instead of a "proper" submit button, you also get extra information sent along with the form data - the x and y coordinates of where you clicked on the image, which obviously with the right cgi script is used to make imagemaps work. You can change the name of this data from x and y using the name="..." attribute, so for instance name="wubble" will return wubble_x and wubble_y. This could be useful to differentiate between different images in the same form, although don't forget that, due to the image acting like a submit button, you will only be able to get the data from one image at a time.


Putting it all together

The following form is an example mailing system. If you examine the source of this document you should be able to find it and copy it for your own use.

Don't forget to change the mailto, mailsubject and linkto options - it won't do anything useful unless you do change them. Also, to change the colours you should do a search and replace for the light blue (#CCCCFF), dark blue (#3300AA) and possibly the white text (#FFFFFF).

Do not use this form as it stands to email Orpheus - any data from this form as it stands will vanish, and won't go through to anyone. If you need to email Orpheus, please contact them though the proper channels.

Quick message
Use this to send a short message to NOBODY
Your name: Your email:
Message:


Documentation based on forms documentation from HTML³ by Richard Goodwin, and reproduced here with permission.
Valid HTML 4.01! Valid CSS!