Why "Controller"?

This package implements a PageController design pattern, which essentially means that there is a single page processing requests and actions this page performs depend on parameters passed in GET or POST data. The pattern is described in more detail on Martin Fowler's website and WACT project website.

What does this mean in application to QuickForm: we have a single script which shows and validates different forms depending on data in request. This allows to fairly easy build very complex forms consisting of several pages (think wizards and such).

The most basic implementation of the PageController pattern would look like

switch ($_REQUEST['action']) {
    case 'foo': 
        doFoo(); 
        break;
    case 'bar': 
        doBar(); 
        break;
    default:
        echo 'Hello, world!';
}

• HTML_QuickForm_Controller: this class extracts the action name from request and calls the appropriate handler. It includes several Pages.

• HTML_QuickForm_Page: this class (extending HTML_QuickForm) represents a single page of a form.

• HTML_QuickForm_Action: this class implements the Command design pattern, i.e. is essentially an OO callback.

Basic usage example

To ease understanding of this package's features, lets take an example form from HTML_QuickForm tutorial and redo it using HTML_QuickForm_Controller:

// Load the controller
require_once 'HTML/QuickForm/Controller.php';
// Load the base Action class (we will subclass it later)
require_once 'HTML/QuickForm/Action.php';

// Class representing a form class FirstPage extends HTML_QuickForm_Page
{
    function buildForm()
    {
        $this->_formBuilt = true;

        // Add some elements to the form
        $this->addElement('header', null, 'QuickForm tutorial example');
        $this->addElement('text', 'name', 'Enter your name:', array('size' => 50, 'maxlength' => 255));
        // Note how we set the name of the submit button
        $this->addElement('submit', $this->getButtonName('submit'), 'Send');

        // Define filters and validation rules
        $this->applyFilter('name', 'trim');
        $this->addRule('name', 'Please enter your name', 'required', null, 'client');

        $this->setDefaultAction('submit');
    }
}

// Action to process the form class ActionProcess extends HTML_QuickForm_Action
{
    function perform(&$page, $actionName)
    {
        echo '<h1>Hello, ' . htmlspecialchars($page->exportValue('name')) . '!</h1>';
    }
}

$page =& new FirstPage('firstForm');

// We only add the 'process' handler, Controller will care for default ones
$page->addAction('process', new ActionProcess());

// Instantiate the Controller
$controller =& new HTML_QuickForm_Controller('tutorial');

// Set defaults for the form elements
$controller->setDefaults(array(
    'name' => 'Joe User'
));

// Add the page to Controller
$controller->addPage($page);

// Process the request
$controller->run();

You may note that the code is more verbose than the original. That is true, but to make a three page wizard-type form you'll only need to create three subclasses of HTML_QuickForm_Page and 'process' event handler based on HTML_QuickForm_Action and add them to Controller, while without the Controller infrastructure it will require a non-trivial amount of programming.

$this->_formBuilt = true;

$this->addElement('submit', $this->getButtonName('submit'), 'Send');

$this->setDefaultAction('submit');

$page =& new FirstPage('firstForm');

$page->addAction('process', new ActionProcess());

$controller =& new HTML_QuickForm_Controller('tutorial');

$controller->setDefaults(array(
    'name' => 'Joe User'
));
$controller->addPage($page);

$controller->run();

Advanced usage examples

...are available in the package archive. Along with the example similar to the provided above, there are two multipage forms:

• Wizard: form pages contain 'Next' and 'Back' buttons and you can't go to the next page unless the current page is valid.

• Tabbed form: form has several pages and buttons allow to go directly to the corresponding page. Form is validated only when the global 'Submit' button is pressed.