HTML_QuickForm_Renderer

HTML_QuickForm_Renderer – Abstract base class for renderers (package developer related)

Description

Defines the abstract methods that should be implemented by child classes.

QuickForm renderers implement the Visitor design pattern. That means that each form element has an accept() method that is called with a renderer instance as a parameter. This method does the following:

  • If the element contains other elements (HTML_QuickForm_group and HTML_QuickForm itself) then it iterates over them calling each element's accept() method and calls the methods for rendering the container itself (e.g. startForm() and finishForm()).

  • If the element is simple, then it calls the renderer's method for rendering itself (e.g. renderHeader()).

It may seem that renderer object has to have a renderConcreteElement() method for each HTML_QuickForm_concreteElement it may visit, but fortunately most of the elements have fairly similar rendering needs, so instead of separate renderTextarea() and renderCheckbox() we have a generic renderElement() method.

The renderer should take care of "accumulating" the information passed to its methods and of generating some type of output based on it. How this is implemented internally depends on the renderer type.

Creating your own renderer

The first thing you have to decide upon is how your renderer will accumulate the information. You'll probably have to create some data structures to keep it (unless you are going to pass the information to e.g. a template object at once).

Then you have to make concrete implementations for all the abstract methods defined in HTML_QuickForm_Renderer. One notable exception is renderHtml() method that is implemented only in the Default renderer and will probably stay this way.

You'll probably also want to add some public methods for customizing the output and getting the results of the renderer's work. But this depends on the type of the renderer very much.

If you want to contribute the renderer you made to QuickForm, consider the following

  • Your code should be useful to other people (e.g. renderer for some obscure private template engine is a bad contribution).

  • Your renderer should have non-trivial usage examples.

  • And last but not least, you code will have to conform to PEAR coding standards.

If you have examples for additional uses of an existing renderer, that will be a welcome contribution, too.