Processing forms with PHPFormMail
PHPFormMail is written in PHP, which rapidly is becoming the language of choice for web developers. PHP is unique among scripting languages in that it originally was designed solely to process content and actions in web pages. PHP has another great strength, its innate ability to connect to many databases, making PHP an excellent choice for creating database-driven, dynamic websites. But, for our purposes, PHPFormMail is a PHP version of a perl script called Matt's FormMail, which has been in widespread use on websites for years. PHPFormMail collects the data entered by a viewer into a web form and then sends this data in an email message to the recipient defined in the form itself. Here is a link to the source of a very simple form:
Simple form source
As you will have noticed, PHPFormMail makes extensive use of hidden form fields to pass information. Let's look at some of the elements in this form, as well as other fields not in use in this particular form:
- <form action="http://www2.ups.edu/php/formmail.php" method="post" name="simpleform" id="simpleform">
- This is the start of the form tag--it contains the URL of the processing script and the post method of sending the form.
- <input type="hidden" name="required" value="my_thoughts">
- The required field indicates which fields of the form must be filled in before the form will processed. This is optional, although you're likely to want to require realname and email (see below). Please note that the field names used in the require statement must match exactly the field names in the form. If they don't match (e.g., one is typed as my_thoughts and the other as My_Thoughts) the form will not be processed.
- <input type="hidden" name="recipient" value="huskamp@ups.edu">
- This identifies the recipient of the email message generated by the form processing. The recipient field is, naturally, required.
- <input type="hidden" name="subject" value="Simple form">
- The text entered into the value of the hidden subject field is the text that's sent in the email message subject line.
- <input type="hidden" name="return_link_url" value="http://www2.ups.edu/web/content/phpformmail.shtml">
- The URL entered into the value of the return_link_url field will place a link to that URL on the results page (more later).
- <input type="hidden" name="return_link_title" value="Back to form article">
- The text entered into the value of the return_link_title will display as the text to be clicked for the link entered in the return_link_url field.
- <input type="hidden" name="title" value="Simple form results">
- The text entered into the value of the title field will become the title of the dynamically-created form results page.
- <input type="hidden" name="css" value="http://www2.ups.edu/css/phpformmail.css">
- The css field, which is optional, will format the form results page according to the qualities stated in the .css file. Feel free to use the URL above, which is a small stylesheet I created to format the display on the results page.
Let's see it in action
This is pretty abstract. Let's see in in action--below is the form discussed above. It specifically demonstrates how a results page looks and the use of a required field. Please fill it out so that you can see how it works. Here's the link:
If you look at the source of this form, you'll see all the hidden fields that are mentioned above. Feel free to make copies and try the form out yourself. There are a few more things to learn first, though, as follows.
Other considerations
PHPFormMail has some very specific qualities and you will need to keep them in mind as you build your forms. What follows is a brief overview.
- realname is a field in PHPFormMail that refers to a person's name.
If realname is requested in the form, PHPFormMail will put this name into the from field of the email message that you receive. (This field will be included in the form results whether you specify it or not.) - email is a field in PHPFormMail that refers to a person's email address.
If email is requested in the form, PHPFormMail will put this email address into the from field of the email message that you receive. (This field will be included in the form results whether you specify it or not.) - The use of descriptive field names will clarify information for you and your visitor.
If you've filled in the simple form above, you'll have seen that the field names and their contents are displayed in the dynamically-created results page. (They look much the same in the email message.) So naming a field date_requested, for example, will be clearer to all than, say, d_r. - The hidden form fields should be placed near the end of the form as in the example.
Some of the hidden fields, such as required, check to see if a criterion is met. If you put the hidden fields near the top of the form, this checking will occur before the respective fields are analyzed. - email is not the same as Email--be sure that the lettercase of the form fields exactly match the lettercase of the fields as they're listed in the hidden required field.
- Some field names have a specific meaning in PHPFormMail and should only be used in the manner documented.
All the field names listed above should only be used as demonstrated. These names include required, recipient, subject, return_link_url, return_link_title, title, realname, and email. It is possible, however, to present the viewer with a selection of recipients and subjects, say, as radio buttons. If you're interested in learning how to do this, please let me know. - Some field names don't work.
By trial and error, I've discovered that the field names sort and gender will not be processed by PHPFormMail. I surmise that these are reserved words in either the form script or in PHP. - If the submit field is given a name in the form, it will be passed on as information.
The submit and reset form actions are the only form elements that do not require a name in HTML 4.x. If you do give the submit button a name, both you and the person filling in the form will see the submit field in the form contents. (You can try this to see the difference.) To keep things clean, do not assign the submit button a name.
Other problems
If you encounter other problems getting the form processor to work, please let me know. I've had to sort out much of this information by trial and error, so your failure will help me learn more.
Multiple Results
From the documentation:
When using checkboxes and multiple selection lists, you'll need to add [] to the end of the field name. When the [] is added, PHPFormMail can then properly process the field and print it out in a comma separated format.
Here's how the happiness_quotient field (sorry) on my simple form looks:
<select name="happiness_quotient[]"> <option value="100%" selected="selected">100%</option> <option value="75%">75%</option> <option value="50%">50%</option> <option value="25%">25%</option> </select>
If you filled out the simple form, you may have noticed that the [] (left and right brackets) present in the form HTML doesn't show up in the form results. They are present only so that PHPFormMail knows how to treat multiple elements in checkbox and multiple selection lists.
Here's another example from the simple form illustrating the use of checkboxes. Note the brackets ([]) at the end of the field name.
<input type="checkbox" name="radiostations[]" value="kuow"> KUOW<br> <input type="checkbox" name="radiostations[]" value="bbc_world_service"> BBC World Service<br> <input type="checkbox" name="radiostations[]" value="kplu"> KPLU<br> <input type="checkbox" name="radiostations[]" value="xm_radio"> XMRadio
Getting a complete email address returned in your form results
PHPFormMail documentation
Here is a link to the PHPFormMail documentation.