PEAR Manual
Prev |  | Next

# Migration to version 3.2

Migration to version 3.2 -- API changes to observe

## Why these changes?

HTML_QuickForm has improved a lot since version 2.x. With the addition of a new renderer layer, a lot of methods that were located in the main QuickForm class were actually duplicates of methods in the renderers. Those methods were kept to give user time to adjust their code. With release 3.2 they will be removed, making QuickForm class much lighter and consistent.

At the same time, file upload validation was moved to the file element as this is a more appropriate place.

Removed methods

- QuickForm related

  - HTML_QuickForm::getAttributesString()

  - HTML_QuickForm::addElementGroup()

  - HTML_QuickForm::addHeader()

  - HTML_QuickForm::addData()

- Renderer related

  - HTML_QuickForm::setElementTemplate()

  - HTML_QuickForm::setHeaderTemplate()

  - HTML_QuickForm::setFormTemplate()

  - HTML_QuickForm::setRequiredNoteTemplate()

  - HTML_QuickForm::clearAllTemplates()

  - HTML_QuickForm_group::setElementTemplate()

  - HTML_QuickForm_group::setGroupTemplate()

- File upload related

  - HTML_QuickForm::isUploadedFile()

  - HTML_QuickForm::getUploadedFile()

  - HTML_QuickForm::moveUploadedFile()

## How to adjust your code

### QuickForm related

HTML_QuickForm::getAttributesString()

      $form->getAttributes(true);

  will return the same value by using HTML_Common::getAttributes() method.
HTML_QuickForm::addElementGroup()

  Arguments order was changed to conform to the way elements are usually added to QuickForm by addElement(). Use HTML_QuickForm::addGroup() instead and swap the element label with the element name.

HTML_QuickForm::addHeader()

  A header is now considered like any other element. There is a new HTML_QuickForm_header element that extends HTML_QuickForm_static. Just use

      $form->addElement('header', $header_name, $header_text);

  This will also allow you to customize the header rendering based on its name.
HTML_QuickForm::addData()

  If you absolutely need this feature, use

      $form->addElement('html', $data)

  or consider using some template-based renderer.

### Renderer related

Those methods are now handled by the renderers. How to use these methods depends on your choice of renderer. With QuickForm default renderer, you can use these methods like that:

    $form =& new HTML_QuickForm('myform');

    $renderer =& $form->defaultRenderer();
    $renderer->setFormTemplate('<table><form{attributes}>{content}</form></table>');
    $renderer->setHeaderTemplate('<tr><td colspan="2"><b>{header}</b></td></tr>');
    $renderer->setGroupTemplate('<table><tr>{content}</tr></table>');
    $renderer->setGroupElementTemplate('<td>{element}<br /><!-- BEGIN required -->*<!-- END required -->{label}</td>');

defaultRenderer()will return a reference to QuickForm integrated renderer. You can of course use any other renderer available in QuickForm such as Sigma, ITX, Smarty, Flexy and so on. Have a look at their documentation to see which methods are available for them.

### File upload related

File-related methods and rules have been moved to the file element HTML_QuickForm_file because it makes more sense this way and you don't have to include upload-related code if you are not using uploads. You have access to these methods like that:

    $form = new HTML_QuickForm('myform');
    $file =& $form->addElement('file', 'myfile', 'Your file:');
    $form->addRule('myfile', 'Cannot exceed 1776 bytes', 'maxfilesize', 1776);
    if ($file->isUploadedFile()) {
        $file->moveUploadedFile('/tmp', 'testfile.txt');
    }

or like that:

    $file =& $form->getElement('myfile');
    if ($file->isUploadedFile()) {
         $fileInfo = $file->getValue();
    }

Prev | Home | Next
QuickForm element types | Up | HTML_QuickForm_Controller