DB_Table Forms Tutorial

Specifying Columns

To limit the fields you want to display, or to change the order, pass a sequential array of column names as the first parameter to getForm()

<?php

// [snip] create the Guesbook object ($GuestBook)

// only show the first name, last name, and email in the form
$cols = array('fname', 'lname', 'email');

// create the <classname>HTML_QuickForm</classname> object
$form =& $GuestBook->getForm($cols);

// display the form
$form->display();

?>

Add Buttons

Unfortunately, the form only has the input fields; it does not yet have "Submit" or "Reset" buttons, which are not automatically generated.

<?php

// [snip] create the $GuestBook GuestBook_Table object

// create the HMTL_QuickForm object
$form =& $GuestBook->getForm($cols);

// add a "submit" button named "op" that says "Go!"
$form->addElement('submit', 'op', 'Go!');

// add a reset button
$form->addElement('reset');

// display the form
$form->display();

?>

Element Label

When a column appears in a form, you can make sure the same label is always applied to it. Let's say we have a column called "other" defined as a 32-character string. We always want it to be labelled as "Other Information" in our forms; use 'qf_label' key like this:

<?php

class GuestBook_Table extends DB_Table
{
 
    var $col = array( 
        // ...  
        'example' => array( 
            // table column definition 
            'type' => 'varchar', 
            'size' => 32, 
             
            // form element definition 
            'qf_label' => 'Other Information'
        )
    ); 
} 
?>

Element Type

By default, DB_Table will try to figure out what kind of form field input type to use for your column. Most column types translate into text fields, but there are some exceptions.

• Boolean columns become HTML_QuickForm 'advcheckbox' fields with values of 0 for not-checked and 1 for checked.

• CLOB columns become HTML_QuickForm 'textarea' fields

• Date columns become HTML_QuickForm 'date' select fields in 'Y-m-d' format.

• Time columns become HTML_QuickForm 'date' select fields in 'H:i:s' format.

• Timestamp columns become HTML_QuickForm 'date' select fields in 'Y-m-d H:i:s' format

To explicitly set the HTML_QuickForm element type for a column, rather than relying on the above defaults, you add a 'qf_type' element to your column definition. You can tell DB_Table to create any of several supported HTML_QuickForm element types by setting the 'qf_type' element to one of these string values:

• 'checkbox' for a single checkbox; maps to the 'advcheckbox' HTML_QuickForm type

• 'hidden' for a hidden element

• 'password' for a password text box

• 'radio' for a set of radio buttons

• 'select' for a select menu

• 'text' for a text box

• 'textarea' for a text area

• 'date' for a date selector; formats as 'Y-m-d'

• 'time' for a time selector; maps to 'date', formats as 'H:i:s'

• 'timestamp' for a timestamp selector; maps to 'date', formats as 'Y-m-d H:i:s'

In this example, we'll make the 'example' column a text field:

<?php

class GuestBook_Table extends DB_Table
{
 
    var $col = array( 
        // ...  
        'example' => array( 
            // table column definition 
            'type' => 'varchar', 
            'size' => 32,
            // form element definition 
            'qf_label' => 'Other Information',
            'qf_type'  => 'text'
        )
    );
}
?>

Element Values

If your column form element is 'checkbox', 'radio', or 'select', you can set the values of the available choices for the form element. You do so via an 'sq_vals' element in the corresponding column definition.

<?php

class GuestBook_Table extends DB_Table
{
 
    var $col = array( 
        // ...  
        'example' => array( 
            // table column definition 
            'type' => 'varchar', 
            'size' => 32,
            // form element definition 
            'qf_label' => 'Other Information',
            'qf_type'  => 'text',
            'qf_vals'  => array(0, 1)
        )
    );
}
?>

<?php

class GuestBook_Table extends DB_Table
{
 
    var $col = array( 
        // ...  
        'example' => array( 
            // table column definition 
            'type' => 'varchar', 
            'size' => 32,
            // form element definition 
            'qf_label' => 'Other Information',
            'qf_type'  => 'text',
            'qf_vals'  => 'array(
                'a' => 'This is the letter "a"',
                'b' => 'I choose "b"',
                'c' => 'No, "c" is always the right answer'
            )
        )
    );
}
?>

Element HTML Attributes

If you like, you can add HTML attributes to the form element using the 'qf_attrs' keys. Attributes are assigned as key-value pairs in an associative array; the keys is the attribute name, and the value is the attribute value. For example, to set the number of rows and columns for a textarea element:

<?php

class GuestBook_Table extends DB_Table
{
 
    var $col = array( 

        // ...  

        'example' => array( 
            // table column definition 
            'type' => 'varchar', 
            'size' => 32,

            // form element definition 
            'qf_label' => 'Other Information',
            'qf_type'  => 'textarea',
            'qf_attrs' => 'array(
                'rows' => 24,
                'cols' => 80
            )
        )
    );
}
?>

DB_Table automatically adds a "maxlength" attribute to text and password elements based on the column size, so that users cannot type in values longer than the column allows.

Element Rules

HTML_QuickForm allows you to add validation rules to the input form. These rules are not the same as the DB_Table automated validations; the HTML_QuickForm rules apply only to the values as they relate to the form itself, not the values related to the table proper. This is an important distinction that will become apparent as you use HTML_QuickForm.

The available rules are:

• email - the form input must be an email address

• lettersonly -- the form nput must consist only of letters

• maxlength -- the form input cannot have more than this many characters

• maxlength -- the form input cannot have fewer than this many characters

• nonzero -- the form input must be greater than or less than zero

• nopunctuation -- the form input may not contain punctuation

• numeric -- the form input must be a number of some sort (no letters)

• regex -- the form input must match a regular expression

• required -- the form input is required to be filled (even with a single space)

• If the column is required ('require' => true), then DB_Table will add a 'required' HTML_QuickForm rule.

• If the column is numeric ('smallint', 'integer', 'bigint', 'single', 'double', or 'timestep') then DB_Table will a 'numeric' HTML_QuickForm rule.

• If the column has a specific size ('size'), then DB_Table will add a 'maxlength' rule.

<?php

class GuestBook_Table extends DB_Table
{

    var $col = array( 
     
        // ...  
         
        'example1' => array( 
            // table column definition 
            'type' => 'integer', 
            
            // form element definition 
            'qf_label' => 'Information', 
            'qf_type' => 'text', 
            
            // a set of QuickForm rules 
            'qf_rules' => array( 
                'required' => 'This field is required.', 
                'numeric' => 'Please use only numbers, no letters.'
            )
        ), 
         
        'example2' => array( 
        
            // table column definition 
            'type' => 'varchar', 
            'size' => 10, 

            // form element definition 
            'qf_label' => 'Something:', 
            'qf_type' => 'text', 

            // a set of QuickForm rules 
            'qf_rules' => array( 
                'minlength' => array('Minimum length is 6 characters.', 6), 
                'maxlength' => array('Maximum length is 10 characters.', 10), 
                'regex' => array( 
                    'Must be only upper-case letters and underscores.', 
                    '/^[A-Z_]+$/'
                )   
            ); 
        )
    ) 
}
?>