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.
Tip:
If you have examples for additional uses of an existing renderer, that will be
a welcome contribution, too.
