Migration from HTML_QuickForm_Controller

Migration from HTML_QuickForm_Controller – Step-by-step guide for porting your scripts to HTML_QuickForm2_Controller

Overview

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.

Controller class and session data

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.

Form page class

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.

Easy building of multipage forms (Previous) Using available handlers and writing custom ones (Next)
Last updated: Fri, 22 Aug 2014 — Download Documentation
Do you think that something on this page is wrong? Please file a bug report or add a note.
View this page in:

User Notes:

There are no user contributed notes for this page.