This guide is intended for current users of HTML_QuickForm_Controller who want to update their scripts to HTML_QuickForm2, which now includes a rewrite of older controller package. It covers major API changes and provides links to further documentation.
It should be noted that API of HTML_QuickForm2_Controller is more similar to API of HTML_QuickForm_Controller than that of HTML_QuickForm2 and HTML_QuickForm. That being said, there are some important differences in method names and behaviour.
Of the methods you are most likely to use in your applications, former HTML_QuickForm_Controller::addAction() is now HTML_QuickForm2_Controller::addHandler() and HTML_QuickForm_Controller::exportValues() is now HTML_QuickForm2_Controller::getValue().
As is the case with HTML_QuickForm2 itself, HTML_QuickForm2_Controller no longer has setDefaults() and setConstants() methods. So instead of former call to HTML_QuickForm_Controller::setDefaults()
<?php
$controller->setDefaults(array(
'foo' => 'default foo value',
'bar' => 'default bar value'
));
?>
you should use HTML_QuickForm2_Controller::addDataSource():
<?php
$controller->addDataSource(new HTML_QuickForm2_DataSource_Array(array(
'foo' => 'default foo value',
'bar' => 'default bar value'
)));
?>
Like with older defaults and constants, Controller DataSources are stored in session. Note that Controller itself does not have a method for replacing the DataSource array similar to HTML_QuickForm2::setDataSources(), use HTML_QuickForm2_Controller_SessionContainer::storeDatasources().
Instead of the former HTML_QuickForm_Controller::container() method that both returned a reference to a session variable storing Controller data and cleared this variable if requested, there is now getSessionContainer() method that returns an instance of HTML_QuickForm2_Controller_SessionContainer wrapping around session variable and destroySessionContainer() method that clears the session variable.
You no longer need to directly access the session variable to store some custom values:
<?php
// Note the references
// on source page:
$data =& $controller->container();
$data['_my_stuff'] = $stuff;
// later on target page:
$data =& $controller->container();
$stuff = $data['_my_stuff'];
?>
you should use instead the storeOpaque() and getOpaque() methods of HTML_QuickForm2_Controller_SessionContainer:
<?php
// on source page:
$controller->getSessionContainer()->storeOpaque('my_stuff', $stuff);
// later on target page:
$stuff = $controller->getSessionContainer()->getOpaque('my_stuff');
?>
SessionContainer also has methods for storing and getting Controller DataSources, form values and form validation statuses, these should be used when writing custom action handlers.
The main difference between HTML_QuickForm_Page and HTML_QuickForm2_Controller_Page is that the latter no longer extends the form class, its constructor accepting an instance of HTML_QuickForm2:
<?php
class TutorialPage extends HTML_QuickForm2_Controller_Page
{
// ...
}
$page = new TutorialPage(new HTML_QuickForm2('tutorial'));
?>
This allows using custom subclasses of HTML_QuickForm2 with Controller and prevents problems like HTML_QuickForm_DHTMLRulesTableless faced, having to include both HTML_QuickForm_DHTMLRulesTableless and HTML_QuickForm_PageDHTMLRulesTableless the former extending HTML_QuickForm and the latter HTML_QuickForm_Page.
$controller
is no longer a public property of Page, use getController() to
access it. Similarly, use getForm() to access the
instance of HTML_QuickForm2.
As with HTML_QuickForm_Controller, former HTML_QuickForm_Page::addAction() is now HTML_QuickForm2_Controller_Page::addHandler(), old HTML_QuickForm_Page::buildForm() is renamed to HTML_QuickForm2_Controller_Page::populateForm().
In new HTML_QuickForm2_Controller_Page::populateForm() one no longer has to do something like
<?php
$this->_formBuilt = true;
?>
as was needed in old HTML_QuickForm_Page::buildForm(), the Page itself now makes sure that populateForm() is called only once.