Overview of QuickForm2_Controller
Вернуться к: HTML_QuickForm2
Overview of QuickForm2_Controller
If you are already familiar with MVC frameworks, then you probably know: controller is a component that accepts user input and instructs other components to perform actions based on that input. HTML_QuickForm2_Controller is somewhat smaller in scope than a typical framework controller since it only deals with forms. When using the Controller, an action name is sent in GET or POST data, usually by clicking a specially named button. This name contains id of one of the form pages added to Controller and name of action handler to call (e.g. 'next' for going forward in a wizard), that data is extracted and an appropriate action handler is called.
Key features:
Allows forms spanning multiple pages, stores form data in session between HTTP requests;
Binds OO action handlers to buttons that submit the form;
Includes default action handlers that allow easy building of multipage forms;
Even if you only use it for single-page forms, form-related logic is kept in classes rather than in procedural code.
Key classes and interfaces:
- HTML_QuickForm2_Controller
Extracts the action name from request and calls the appropriate handler. Contains several Pages and a wrapper for values stored in session.
- HTML_QuickForm2_Controller_Page
Class representing a single page of the form. Contains an instance of HTML_QuickForm2.
- HTML_QuickForm2_Controller_Action
Action handlers implement this interface.
HTML_QuickForm2_Controller is a rewrite of PHP4 HTML_QuickForm_Controller, so if you are already using the latter you can go to migration guide which contains step-by-step instructions for porting your scripts to new package.
Basic usage example
Session initialization
This simple example does not use sessions since there is no need to pass data between pages. You'll need to use sessions when dealing with a real multipage form, though. HTML_QuickForm2_Controller does not start a session automatically, you should explicitly call session_start() before instantiating the controller class.
The same example form that was used in the package's tutorial will now be rewritten using the Controller:
Builds and processes a form with a single input field, using Controller
<?php
// Load the main class
require_once 'HTML/QuickForm2.php';
// Load the controller
require_once 'HTML/QuickForm2/Controller.php';
// Load the Action interface (we will implement it)
require_once 'HTML/QuickForm2/Controller/Action.php';
// Class representing a form page
class TutorialPage extends HTML_QuickForm2_Controller_Page
{
protected function populateForm()
{
// Add some elements to the form
$fieldset = $this->form->addElement('fieldset')->setLabel('QuickForm2_Controller tutorial example');
$name = $fieldset->addElement('text', 'name', array('size' => 50, 'maxlength' => 255))
->setLabel('Enter your name:');
// We set the name of the submit button so that it binds to default 'submit' handler
$fieldset->addElement('submit', $this->getButtonName('submit'),
array('value' => 'Send!'));
// The action to call if a user presses Enter rather than clicks on a button
$this->setDefaultAction('submit');
// Define filters and validation rules
$name->addFilter('trim');
$name->addRule('required', 'Please enter your name');
}
}
// Action to process the form after successful validation
class TutorialProcess implements HTML_QuickForm2_Controller_Action
{
public function perform(HTML_QuickForm2_Controller_Page $page, $name)
{
$values = $page->getController()->getValue();
echo '<h1>Hello, ' . htmlspecialchars($values['name']) . '!</h1>';
}
}
$page = new TutorialPage(new HTML_QuickForm2('tutorial'));
// We only add the custom 'process' handler, Controller will care for default ones
$page->addHandler('process', new TutorialProcess());
$controller = new HTML_QuickForm2_Controller('tutorial');
// Set defaults for the form elements
$controller->addDataSource(new HTML_QuickForm2_DataSource_Array(array(
'name' => 'Joe User'
)));
$controller->addPage($page);
// Process the request
$controller->run();
?>
You may note that the above code is more verbose than the original. While that is definitely true, to make a three page wizard you'll only need to create three subclasses of HTML_QuickForm2_Controller_Page, a 'process' handler and add them to Controller, which already has default handlers for typical 'Back' and 'Next' buttons. It will require a non-trivial amount of programming without the Controller infrastructure.
Creating form pages
To define pages for your controller you need to subclass HTML_QuickForm2_Controller_Page implementing its abstract populateForm() method. Note that this method will be called on demand (i.e. only when the user sees the form in question), so it is better performance-wise to keep all form-building code in it than to pass a pre-populated instance of HTML_QuickForm2 to page's constructor.
Most of the code in the method just repeats what was done in the original tutorial, however some of it requires explanation:
<?php
// We set the name of the submit button so that it binds to default 'submit' handler
$fieldset->addElement('submit', $this->getButtonName('submit'),
array('value' => 'Send!'));
// The action to call if a user presses Enter rather than clicks on a button
$this->setDefaultAction('submit');
?> The first line uses getButtonName() to set a special name for form's submit button and thus trigger a 'submit' action on a 'tutorial' form when that button is clicked (default handler for such action is implemented in HTML_QuickForm2_Controller_Action_Submit). The second one sets an action to trigger when no submit button is clicked (e.g. user presses Enter instead of clicking). Under the hood this is done by adding an instance of HTML_QuickForm2_Controller_DefaultAction to the form.
Creating custom action handlers
You'll usually need custom handlers for only two actions:
- 'process'
Called when the form is submitted and passes validation. In case of multipage forms that means that all the pages are valid.
- 'display'
Called when a form page needs to be displayed. It does have a default handler, but usually you'll want to tweak the output.
'process' handler is, obviously, completely application-specific and will usually deal with storing the form values somewhere. When creating a custom 'display' handler it is easiest to subclass HTML_QuickForm2_Controller_Action_Display and override its renderForm() method to use a Renderer or do any other tweaks you like.
Setting up the controller
First we instantiate the custom Page class and add a custom action handler to it
<?php
$page = new TutorialPage(new HTML_QuickForm2('tutorial'));
// We only add the custom 'process' handler, Controller will care for default ones
$page->addHandler('process', new TutorialProcess());
?> We don't bother with other action handlers as Controller will automatically load and use them.
Then we instantiate the controller
<?php
$controller = new HTML_QuickForm2_Controller('tutorial');
?> Note that Controller needs an id and it should be unique if you have several Controllers in application, as it is used for storing values in session.
Then we add a DataSource and the page to the Controller
<?php
// Set defaults for the form elements
$controller->addDataSource(new HTML_QuickForm2_DataSource_Array(array(
'name' => 'Joe User'
)));
$controller->addPage($page);
?> While it is possible to add DataSource to an instance of HTML_QuickForm2 within Page instead, the above code allows setting the default values for the whole (possibly multipage) form. Note also that Controller's DataSources, unlike form's, are stored in session.
Finally we call the Controller's run() method
<?php
$controller->run();
?> which takes care of finding the name of the current action and calling the necessary handler.
Further usage examples
More complex usage examples are installed with the package. Along with the form similar to the above they include 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 corresponding buttons allow going to the desired page whether current one is valid or not. The global 'Submit' button will not allow form processing, however, unless all pages are valid.
Controller examples are installed to directory HTML_QuickForm2/examples/controller under PEAR's doc_dir. If you have trouble finding where doc_dir is, you can use config-show command of PEAR installer.
Вернуться к: HTML_QuickForm2