Location: PHPKode > scripts > FormBuilder > formbuilder-51140/tutorial.txt
FormBuilder Tutorial
version 1.0b2 (Second Public Beta)

http://www.rodesia.org/?section=FormBuilder

1 - Introduction
2 - Creating a guestbook
3 - FormBuilder basics
4 - Customizing FormBuilder
5 - CSS Reference


1 - Introduction
----------------

FormBuilder is a PHP class that simplifies the process of creation and validation of HTML forms. It can also output the results in a text form and email them.

FormBuilder in essence manages a collection of field classes that implement a standard interface defined by the FormField class. Classes currently implemented include text fields, radio buttons, checkboxes, popup menus, date/time, etc.

The generated form can be fully customized through CSS. A list of the CSS elements used by FormField is described further in the chapter _CSS Reference_.

The current version of FormBuilder is already very usable, but there are some improvements in planning:
- Better validation
- More types of Fields
- Database integration



2 - Creating a guestbook
------------------------

The best way to explain how FormBuilder works is to go through a simple example, in this chapter we are going to create a guestbook for a website.


// The first step is to include the FormBuilder class

require_once('FormBuilder.php');

// Then FormBuilder needs to be initialized

$form = new FormBuilder();

// insert some fields into the form

$form->addField(new TextField('Name:', 'name', 25, 2, 30));
$form->addField(new TextAreaField('Text:', 'textArea', 1, 100, 5, 40));
$form->addField(new SubmitField('submit', 'Send'));

// Next, check if the form has already been submitted,
// or if this is the first time the form is displayed

if ($form->isSubmitted('submit'))
{
    // Form has been submitted, so validate it.
    $form->validate();
    
    if ($form->isValid())
    {
        // The form is valid, display some success message
        echo '<p>Thank you for submitting the form!</p>';
        
        // now the contents of the form can be sent by email,
        // displayed on screen, or stored in a database.
    }
    else
    {
        // Form is invalid, show an error message and display the
        // form again
        
        echo '<p>The form is invalid, please correct the highlighted '.
             'fields, and submit again</p>';
        
        $form->display();
    }
}
else
{
    // This is the first time the page is loaded, so display the form
    $form->display();
}



3- FormBuilder Basics
---------------------

After creating a new form, the next step is to add form fields to it, this is done with the addField() method:

$form->addField(new TextField('Name:', 'name', 25, 2, 30));

in the previous line, a new TextField is created, check the _Reference_ section for a description of the syntax of all the available fields.

When all the fields are added, the form can be displayed inside a webpage:

$form->display();

To check if a form has been submitted, call the isSubmitted() method with the name of the button to check. For example, to check if the button with name 'submit' has been submitted to the following:

if ($form->isSubmitted('submit'))

After checking that a form has been submitted, it needs to be validated

$form->validate();

When the form is validated and checked to be valid with isValid(), the values from individual fields can be retrieved, the whole form contents can be retrieved in text form, or sent by email:

- getting the value of a form field:
  $form->getValue('name');
  
- getting a text representation of the submitted form:
  $form->generateText();
  
- sending an email with the form contents:
  $form->sendMail('Website', 'hide@address.com',
			      'hide@address.com', 'Some subject');


A more detailed example - fb_example.php - can be found in the same directory as this tutorial.



4 - Customizing FormBuilder
---------------------------

FormBuilder can be easily adapted to diferent languages and time and date formats.

To define the date time display formats there are 3 constants:

// default date and time format for the DateTimeField class
define ('FB_DEFAULT_DATETIME_FMT', 'd-M-Y t');

// date format for the DateField class
define ('FB_DEFAULT_DATE_FMT', 'd-M-Y');

// time format for the TimeField class
define ('FB_DEFAULT_TIME_FMT', 't');

in the formatting string FormBuilder recognizes the following chars as commands:
Y - year, 4 digits (eg. '2005')
m - month, numeric form, zero padded (eg. '08')
M - month, literal (eg. 'Dec')
d - day, zero padded (eg. '01')
t - time (hh:mm) in 24 hour format (eg. '14:30')
T - time (hh:mm am/pm) in 12 hour format with am/pm appended (eg. '11:00am')

Non recognized chars will be printed on screen.


The following items are language dependent strings:

// Used in the text output of CheckboxFields, 'Yes' means selected
$FB_YESNO = array ('No', 'Yes');

// These vars are used in the DateTimeField and related classes.
$FB_MONTHS = array ('Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul',
                    'Aug', 'Sep', 'Oct', 'Nov', 'Dec');
$FB_AMPM = array ('AM', 'PM');
$FB_DATETIME_BLANKS = array ('Y' => '[year]', 'm' => '[month]', 'd' => '[day]',
                             'hour' => '[hour]', 'minute' => '[minute]',
                             'ampm' => '[AM/PM]');



5 - CSS Reference
-----------------

FormBuilder's appearance can be fully customized though CSS.
The following classes are used:

FormBuilder - table that contains the fields
        
FormBuilder h4  - applied to the LabelFields
        
warning - used on the labels of invalid fields
        
required - used on the required '*' identifier
                
fieldLabel - used on labels
Return current item: FormBuilder