Using HTML_QuickForm To Manage Web Forms, Part 2 - Dressing Up Your Web Form
(Page 4 of 7 )
One of the goals of my research, initially, was that I do not want to code any HTML in my PHP scripts. I must admit the HTML_QuickForm package did not let me down on that count. But we do not live in a utopian world and - based on past experiences - there will come a time when I need to tweak the associated HTML code.
For example, you might have noticed that I have used the "html" control to manually insert HTML code in all of my examples so far. This can be avoided if I could update the default template itself.
Fortunately, the developers of this package were also up to the task and came up with the concept of "renderers." In simple English, a "renderer" is the mechanism that is responsible for painting the Web form on the screen. The HTML_QuickForm package is equipped with such a renderer, which is responsible for the layout of the Web forms in all previous examples.
Can I tweak the default templates associated with the HTML_QuickForm package?
Check out the next code listing:
Code Listing 3
Load this script in your browser to view the following output:
Notice that I have successfully inserted the desired spacing before and after the "headers" controls without the use of the "html" control. Another significant update: the labels displayed alongside each Web form control is left-aligned.
Let us understand the code behind this transformation:
<?php
// snip
// create an instance of the default renderer object for
// our local reference
$renderer =& $obj_registration_form->defaultRenderer();
$renderer->setFormTemplate(
'<form{attributes}>
<table width="600" border="0" cellpadding="5" cellspacing="5">{content}
</table>
</form>'
);
$renderer->setElementTemplate(
'<tr>
<td align="left" style="font-weight:bold;" valign="top">{label}
<!-- BEGIN required --><span style="color: #ff0000">*</span><!-- END required -->
</td>
<td align="left">{element}
<!-- BEGIN error --><br /><span style="color: #ff0000;font-size:10px">{error}</span><!-- END error -->
</td>
</tr>'
);
// snip
?>
Once I have created a local instance of the HTML_QuickForm() object, I obtain a reference to the "behind-the-scenes" HTML_QuickForm_Renderer_Default() object by invoking the defaultRenderer() method.
This renderer object is equipped with a bunch of methods to modify the default templates. And if you are really curious, the official documentation lists the default templates. Use these as a reference, just as I did.
Back to my code snippet: first, I have used the setFormTemplate() method that allows me to update the template that renders the <FORM> and <TABLE> elements. Note the use of the following special markers in the template: the {attribute} marker represents the attributes of the <FORM> element and the {content} tag is replaced by the HTML code generated for the <FORM> elements.
Next, I have the setElementTemplate() method - this represents the template used to render every <FORM> element. For this template, the {label} tag is replaced by the label passed to the addElement() method, the {element} tag is replaced by the HTML code for the <FORM> control and the {error} tag is replaced with the error message passed to the addRule() method and is only displayed when an error occurs.
If you look closely, you’ll notice two additional markers: first, all HTML code placed between "<!-- BEGIN required -->" and "<!-- END required -->" markers is displayed if a particular element is compulsory and second, the content between "<!-- BEGIN error -->" and "<!-- END error -->" is only displayed if an error is raised for a particular control.
<?php
// snip
$renderer->setHeaderTemplate(
'<tr>
<td colspan="2"> </td>
</tr>
<tr>
<td colspan="2" style="font-size:16px;background-color:#DDDDDD;font-weight:bold">{header}</td>
</tr>
<tr>
<td colspan="2"> </td>
</tr>'
);
$renderer->setGroupTemplate(
'<tr>
<td colspan="2"> </td>
</tr>
<tr>
<td colspan="2" align="center">{content}</td>
</tr>',
'grpSubmitReset'
);
$renderer->setGroupElementTemplate(
'{element}',
'grpSubmitReset'
);
$renderer->setRequiredNoteTemplate(
'<tr>
<td colspan="2" align="center"><span style="color:#FF0000;font-size:10px">* indicates Required Field</span></td>
</tr>'
);
// snip
?>
As the name suggests, the setHeaderTemplate() method allows us to update the template associated with the "header" control.
Next, I’ve used setRequiredNoteTemplate() method to update the template that displays the "required" field message. Note that the renderer invokes this function after all other controls have been painted on the screen. So, you will find that message is always displayed under the last <FORM> control on the Web form.
The combination of setGroupTemplate() and setGroupElementTemplate() allows me to customize the template for a specific group. Accordingly, I have updated the template for the "grpSubmitReset" group to include some space above the "Register" button in the Web form.
While the modifications may be cosmetic in nature, the example does demonstrate the versatility of the HTML_QuickForm_Renderer_Default() object and if you want to know more, I recommend that you visit the following URL: http://pear.php.net/manual/en/package.html.html-quickform.intro-renderers.php.
Next: Getting Smart with HTML_QuickForm >>
More Design Usability Articles
More By Harish Kamath
