Web Team Home » Documentation Index » Documentation Example

Using the form.php script to email information from web forms

Introduction

The HSS Web Team have provided a PHP script at http://www.hss.ed.ac.uk/web-team/util/form.php that may be used to e-mail the data collected in an HTML form to any user in the University of Edinburgh. This page documents the use of that form.

In order to collect information on a web page you need to create an HTML form using the <form ... > ..... </form> element.

Here is an example form:

<form method="post" action="http://www.hss.ed.ac.uk/web-team/util/form.php">

   <input type="hidden" name="PostParameter" value="mail=someone@somewhere" />

   <p>

     <label for="user">User Name:<br/></label>

     <input type="text" id="user" name="User Name" size="30"  value="Enter your name here" />

   </p>

   <p><label for="email">EMail Address:<br/></label>

     <input type="text" id="email" name="email" size="30"  value="Please put your email address here">

   </p>

   <p><label for="message">Message to be sent:<br/></label>

      <textarea rows="5" cols="30" id="message" name="message">

           A short message may be sent here.

      </textarea>

   </p>

   <p><input type="submit">

</form>

The following fields have been declared in this form:

PostParameter: This is a special 'hidden' field that is not displayed to the user.; It contains information that is used by the script that handles the form. See the notes below about what may be put in it.
User Name & email: These display input boxes 30 characters wide into which the user may enter a single line of text.
message: This displays an input area 30 columns wide and 5 rows deep into which the user may enter text.
submit: This causes a button to be displayed. When this is selected by the user, the information gathered in the form is sent off for processing by the script.

When displayed on the screen the output looks something like:

When the submit button is selected the form information is sent off to the script http://www.hss.ed.ac.uk/web-team/util/form.php. This script then interprets the information in the PostParameter field and sends the information from the other fields to the email address someone@somewhere.

The PostParameter field

The field that controls the script is PostParameter. It should contain a control=value pair where control is one of:

mail

This field is required and should appear something like

mail=username@host.ed.ac.uk

This field may contain more than one email address (with commas between them) although this is not recommended. If you want the output to go to more than one address you would be best to put a number of mail= lines in the PostParameter. (See the examples below.)

Addresses not in the Edinburgh mail domain (ie not ending ed.ac.uk will not be processed. Clearly, you would normally put your own email address in here.

subject

This optional field may contain something like

subject=Input from Web form

This will be used as the subject line in the mail message generated.

require

This optional field may be used to specify fields that must be filled in for the form to be processed.

It may take one of two forms:

require=User Name,message

require all

In the first of these you should supply a comma separated list of the names of the fields that must be filled in. I the second form you may specify that all fields must be filled in. (Note that there is no equals sign in the second form.)

from

This optional field may be used to specify that one of the input fields is to be treated as the from field of the email message generated. Normally this is so that you may reply to whoever filled in the form. For example:

from=email

Note that if you require this field to be filled in you will also have to include a require entry.

Alternatively, you may wish to have a fixed from address in the message. This may be done by setting the above postparameter field and including a hidden field containing the value. (See below for an example)

If you do not have this set then the default value will be automailer@ed.ac.uk (Web Form: Please do not reply) (any replies to this address will be discarded unread)

blockHTML

This optional field may be specified if you want to have HTML in any of the input fields of your form. This may be useful if you are wanting to recieve html in the content of the email. This block works by scanning for any <alphabetical...> pattern so it may also reject fully qualified email addresses of the form <user@example.com> Email addresses in a field specified by the 'from' postparameter will be exempt from this check.

The Default for this funstion is 'yes' meaning that it will automatically strip out the HTML without being asked to remove this feature the command

blockHTML=no

will have to be used.

formOK

This optional field may be used to specify the full URL of a page to be displayed in the event of successfull completion. For example:

formOK=http://www.myserver.ed.ac.uk/misc/formsent.html.

formFAIL

This optional field may be used to specify the full URL of a page to be displayed in the event of an error in processing the form input. For example:

formFAIL=http://www.myserver.ed.ac.uk/misc/formfailed.html

The web page specified will be displayed with a query string containing the error message generated.

title

This optional field may contain something like

title=Input information accepted

This will appear in the screen displayed when the form has successfully completed its processing.

ammendvars

This optional field can be used to add useful information to the end of an email to help identify the user sending the information and speed up resolution of queries.

-----------------------
 United Kingdom D/T:Mon 21st May 2012 - 06:18:47
 REMOTE_ADDR: 38.107.179.232
 REMOTE_HOST: 
 getenv-HTTP_CLIENT_IP: 
 getenv-HTTP_X_FORWARDED_FOR: 
 HTTP_HOST: www.hss.ed.ac.uk
 gethostbyaddr: 38.107.179.232
 REMOTE_PORT: 49829
 HTTP_USER_AGENT: CCBot/1.0 (+http://www.commoncrawl.org/bot.html)

To activate this field add the variable:
ammendvars=yes
to the postparmter

For compatibility with an earlier version of this program it is possible to have multiple control=value pairs in a single web form field but these have to be on different lines.

An example of a PostParameter entry

 <input type="hidden" name="PostParameter" value="mail=X.Q.Jones@ed.ac.u
    						format=plain
    						blockHTML=yes
    						mail=lunar.society@ed.ac.uk" />
 <-- This is an example of a multi-line PostParameter    -->
 <-- Note carefully where quotes are used (and not used) -->

General notes

If you want to limit the amount that may be typed into an input box then you should use the HTML construct <input name="fieldname" maxlength=30> (However some browsers may not implement this correctly.)

You should, of course, check that any form you provide works correctly. Be careful that the mail address provided is correct - while the script will check that it appears to be a valid mail address within the University this checking cannot be absolutely complete. In the event of it being wrong it is likely that no error will be reported.

Error messages generated by the script

No POST values detected or POST value "PostParameter" not detected.: This indicates an error in the form itself - please check it and add the PostParameter field.
The email field is blank.: This indicates an error in the form itself - the mail= part of the PostParameter field doesnt appear to be there.
someone@somewhere is not a valid email address: This indicates an error in the form itself - while the mail= part of the PostParameter field is there, the address supplied doesn't appear to be a valid email address.; This could also be triggered by the from address field.
External email address: This form only supports internal addresses.: This indicates an error in the form itself - while the mail= part of the PostParameter field is there it appears to specify an address that is not part of the University (ie ending ed.ac.uk). This restriction has been placed to stop forms using this script from being able to cause a nuisance outside the University. If there are particularly good reasons for having external addresses contacted via this script then please contact the HSS Web Team.
'{field name}' is a required field and has been left empty: This indicates an error on the part of the user who has failed to fill in some required fields in the form. The fields that need to be filled in will be listed.
This System has detected patterns in the message just sent that indicate that it contains spam: This message will have one of two possible additional pieces of text.

Excessive use of the ! and * characters are characteristic of spam emails
Spam emails tend towards using an excessive number of exclamation marks and asterisk characters as a result this system will block emails that contain too many of these characters.

Signs of advertising or explicit terms will trigger this error.
This error occurs when an explicit term or phrase is found anywhere in a message, This feature was implemented as a result of advertising spam reaching the web-team's email address, the messages sent have been used as examples and explicit terms extracted, this should reduce the bogus emails as this service should not be used for advertising or the sending or explicit or offensive messages.

Displaying errors when redirecting to formFAIL

When redirecting using formFAIL error messages are stored in the session variable

$_SESSION['QUERY_STRING']

and the errors are seperated by XHTML line breaks at the end of each line <br /> below is a simple PHP script that can be included in a document that will display the errors on multiple lines.

session_start();
// if the page is refreshed then this will not be set so do not use it
if(isset($_SESSION['QUERY_STRING'])){
	// get the error data from the server
	$data = $_SESSION['QUERY_STRING'];

    // break the error string up by the <br /> tags
	$data=explode('<br />',$data);

	// if there are results then there is an error, display it
	if(count($data)>0){
		echo "<ol>";	// begin ordered list
		for($i=0;$i<count($data)-1;$i++){

			// display
			echo "<li>".$data[$i]."</li>";

		}	// end of foreach
        echo "</ol>";// end ordered list
     }	// end of if
    // unset the session vaiable so it does not interact with anything else
	unset($_SESSION['QUERY_STRING']);
}

Comments

Your comments on the script, its functionality and this document would be appreciated

Click here to leave your comments

This page was last modified on Tue, 13 May 2008 11:37:10 +0100

Skip Menu

Main Content