HTML_QuickForm2_Renderer_Default is essentially a primitive template engine (only supporting blocks and variable placeholders) that is intended for quick prototyping. This Renderer is used under the hood by a magic __toString() method of HTML_QuickForm2_Container (and consequently HTML_QuickForm2 itself). It is similar to HTML_QuickForm_Renderer_Default of HTML_QuickForm though has different template format and more customization possibilities.
Generated HTML is returned by a magic __toString() method, so the renderer can be used in string contexts.
The elements are output in the order they were added using an appropriate template, which looks similar to the following:
<div class="row"> <p class="label"> <qf:required><span class="required">*</span></qf:required> <qf:label><label for="{id}">{label}</label></qf:label> </p> <div class="element<qf:error> error</qf:error>"> <qf:error><span class="error">{error}<br /></span></qf:error> {element} </div> </div>
Here {foo}
are placeholders that will be replaced by actual element data and
<qf:bar>...</qf:bar>
are blocks that will be either removed if an
element does not have a bar
property or will be retained without their
<qf:bar>
delimiters if said property is present.
The following placeholders are recognized and will be replaced:
{id}
'id'
attribute of an element.
{class}
'class'
attribute of an element. Mostly needed to put repeat-specific
repeatItem
and repeatPrototype
CSS classes on a outer
<div>
for a group.
{attributes}
{error}
{label}
{label_more}
'more'
key.
{element}
{content}
{hidden}
group_hiddens
is on. Only in template for
form.
{errors}
group_errors
is on. Only in template for form.
{reqnote}
{message}
The following blocks are possible:
<qf:required>
<qf:error>, <qf:label>, <qf:label_more>, <qf:reqnote>, <qf:message>
<qf:error>
is also used to set a special CSS class
for an invalid element.
Form element templates are set by setTemplateForId(),
setTemplateForClass(),
setElementTemplateForGroupId()
and setElementTemplateForGroupClass().
The latter two methods apply to elements that are inside Groups. Note that the word
"class" in these method names refers to PHP class name rather than to CSS class name.
The renderer will also try going up the class hierarchy, so it will use a template for
HTML_QuickForm2_Element to render <input type="text"
/>
if more specific templates for
HTML_QuickForm2_Element_InputText and
HTML_QuickForm2_Element_Input are not available.
Another template-related method is setErrorTemplate()
which sets templates for errors output when group_errors
is TRUE.
When searching for an appropriate template for a given element, the following order is used:
When rendering elements inside Container, two templates are actually used:
{content}
placeholder;
Elements are first wrapped in their own templates, then {content}
placeholder
in Container template is replaced by HTML for all contained elements.
This is true for Groups as well, but is less obvious:
'{element}'
. So you will only get elements' HTML, maybe with separators in
between, no additional markup.The above also means that you will see neither labels for grouped elements, nor their validation errors by default. If you want to output these, you'll need to set a new template for grouped elements using either of setTemplateForId(), setElementTemplateForGroupId(), setElementTemplateForGroupClass():
<?php
// setElementTemplateForGroupId() may be used if you want to customize a specific group
$renderer->setElementTemplateForGroupClass(
'HTML_QuickForm2_Container_Group', 'HTML_QuickForm2_Element',
'a complex template with {element}, {label} and {error} placeholders'
);
?>
controller/wizard.php
example installed with the package shows setting a complex template for grouped elements.