Do you need to collect information from people you do business with? Would it be easier for you if they could just visit your web site, type the information directly into a web-based form and have the form emailed to the person responsible for that information? If so, this article is for you.

This ezform script was written to be a very, very simple solution for BNT Solutions web customers. Simply download this script and install it in your web site, then follow the instructions to produce you own web based forms. It's designed to be painless, fast and easy to use. We hope you'll like it.

Note that there is a downside to keeping things this simple: You will want additional features but they're not available through this super-simple library. Still, this code will get you started and you can find something more sophisticated later.

Note: This article includes source code in PHP for your PHP-capable web site. A small amount of programming experience is required. If your web site is hosted by BNT Solutions, you can ask for this feature to be installed for you. Please take a moment to contact your site administrator for more details.

EZ Form Mail

Preamble

A quick and easy library for generating forms that are emailed from your web site.

Copyright (C) 2006 by Sam Azer, All Rights Reserved.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the

Free Software Foundation, Inc.
51 Franklin Street
Fifth Floor, Boston, MA
02110-1301, USA.

Documentation

This file contains the documentation for the ezform class. The software class and basic and advanced example files are available in the package files, which you can download from here:

• ezform-1.0.tgz (~15k)
• ezform-1.0.zip (~20k)

Installation

The ezform.inc file should be saved in a convenient directory and included somewhere in your web page.

If you are running a CMS like Joomla or Drupal or Visual Power Web, you might want to include this file in one of the startup scripts for the CMS so that non-technical users can use it in their pages. Otherwise, each web page that wants to present and process a form will have to include this file first:

include(  "ezform.inc"  );

Default Values

At the top of the class is a list of variables and their default values. These values should be edited to make sense for your web site.

Setup

For each form that the user wants to have on his web page, it is necessary to create an instance of the form object. Because the ezform class automatically assigns a default name to the form, you can create the first form object like this:

$form  = new  ezform ();

After executing the above line, the $form variable contains an object of type ezform. By default, the name of the web form that this object will emit will be "form2email"

If you want to have more than one form on the page, you should assign different form names to each one, like this:

$form1  = new  ezform ( "first_form" );
$form2  = new  ezform ( "second_form" );

For each form, it is probably necessary to set the from, to and reply_to email addresses (although the defaults may be acceptable,) along with the subject/title of the form. For example:

$form -> from      =  " This e-mail address is being protected from spam bots, you need JavaScript enabled to view it " ;
$form -> to        =  " This e-mail address is being protected from spam bots, you need JavaScript enabled to view it " ;
$form -> reply_to  =  " This e-mail address is being protected from spam bots, you need JavaScript enabled to view it " ;
$form -> subject   =  "Appointment Request" ;

You might also want to tell the object what to say to the user when it sends an email containing form data:

$form -> confirmation  =  "<font color=red>"
             .  "<b>Information Sent/Envoyer</b>"
             .  "</font>"
             ;

The confirmation above, Information Sent, is the default confirmation sent by ezform. If this is acceptable to you, you don't need to change it.

Listing the Questions

Next, you need to tell the form what questions it should be asking of the user. For example:

$questions  = array(

        array(  "Text" ,  20 ,  "Your First/Given Name"  ),
        array(  "Text" ,  20 ,  "Your Last/Family Name"  ),
        array(  "Text" ,  32 ,  "Your EMail Address"  ),
        array(  "Text" ,  20 ,  "Desired Appointment Date"  ),
        array(  "Text" ,  10 ,  "Desired Appointment Time"  ),

        );

Notice that the Questions variable contains an array of question arrays. Each question is an array containing three elements:

• The type of data the user is being asked to provide. At the time of this writing, only one type of data is supported: text. Later, ezform may support additional types such as Yes/No, True/False, dates, times, text blocks, email address, etc.
• The maximum number of characters anticipated in response to this question. At the time of this writing, this field length specification is not enforced, but it is used to estimate the required width of the text box that the user will be typing in.
• The text of the question that the user will answer.

There is no limit on the number of questions you can have in the Questions array.

Preparation

ezform needs to prepare for the form handling operation. This is done when you pass the list of questions to the ezform object, like this:

$form -> prepare (  $questions  );

Normally, the $form->prepare($q) line does not emit any text into your web page. However, after a form has been processed and an email has been sent, this function will emit the Confirmation text.

Displaying the Form

Finally, you need to tell ezform where to display the list of form questions. There are two ways to do this:

• Let ezform display the questions in a simple table format.
• Create your own form layout and let ezform emit the necessary form-related HTML code only.

Simple Form Display

To let ezform display the questions automatically, just call the show() method of the form object, like this:

$form -> show ();

That's all you really need to do for a simple form. Ezform will emit a simple table with one line per form question. This table will be formatted in a very simple manner and is not necessarily going to win any prizes for appearance - but it will be easy to understand and use.

Advanced Form Display

If you want to make a bit more effort to make a pretty form, you can instruct ezform to provide all the necessary HTML form code like this:

echo  $form -> begin ();   // emit the <form> tag

echo  $form -> label ( 0 );  // emit the label text for the first question
echo  $form -> field ( 0 );  // emit the form code for the first question

echo  $form -> label ( 1 );  // ...second question...
echo  $form -> field ( 1 );  // ...second question...

echo  $form -> label ( 2 );  // ...etc...
echo  $form -> field ( 2 );  // ...etc...

echo  $form -> label ( 3 );  // ...etc...
echo  $form -> field ( 3 );  // ...etc...

echo  $form -> label ( 4 );  // ...etc...
echo  $form -> field ( 4 );  // ...etc...

echo  $form -> buttons ();  // emit the RESET and SUBMIT buttons
echo  $form -> end ();     // emit the </form> tag

Of course, this more advanced method requires that you surround the above PHP code with your own HTML web page formatting instructions in the expected manner:

<?= $form -> begin ();  ?>
<table border=0>
<tr>
   <td><?php = $form -> label ( 1 );  ?> </td>
   <td><?php = $form -> field ( 1 );  ?> </td>
</tr>
...
<tr><td colspan=2><?=$form -> buttons ();  ?> </td></tr>
</table>
<?=$form -> end ();  ?>

When the user views the resulting page, he will see the ezform. When he fills the form with data and submits the form, the form will perform a post operation back to the same web page. Ezform will collect the data and prepare an email which will be sent to the specified address. It will also emit the confirmation message to the web page so that the user will see that an email was sent.

For more information on how to use ezform, try the supplied test forms and play with them to see what happens when you make changes.

Advanced Functionality

ezform contains a function that returns false when displaying a normal page and true when processing a form post operation. This can be used to determine if a form post operation has taken place. This is useful, for example, when you want to have a form that is cc'd to the person who submitted it. If the person is supposed to put his email address in Question #0, for example, the code might look like this:

if (  $form -> inpost () )
    $form -> cc  =  $form -> data ( 0 );

$form -> prepare (  $questions  );

This adds a comma and the users' email address to the To email address. Note that this must be done before the prepare() method is called.