HTML_QuickForm_Renderer_QuickHtml
Description
This renderer has three main distinctives: an easy way to create custom-looking forms, the ability to separate the creation of form elements from their display, and being able to use QuickForm in widget-based template systems.
All of the renderers allow you to create a custom-looking form. However, unlike the default renderer, QuickHtml is solely for creating custom forms and has the additional benefits discussed below.
It is often desirable to separate the creation of form elements and their accompanying rules from their actual display on a page. For example, in the MVC design pattern it may be useful to create the form elements and their rules in the Model classes which control how the submitted data will be saved (field lengths, allowed characters, etc.), but leave the rendering of those form elements to the View classes which only care about how to make the page look a certain way.
A widget is a chunk of re-usable html which can be used with other widgets to create a webpage. Any template system which supports widgets (and nearly all do) can be used with QuickHtml. An example widget may consist of a table with reserved places for the form elements. The form elements would be rendered into those places and then the form tags, any remaining form elements (such as hidden elements), and any accompanying javascript for validation would be wrapped around the table widget.
Usage example
The following is an example usage of the QuickHtml renderer. The
"template" system we use is just a simple html widget in which the form
elements are placed, but it could be replaced with a more complex
template system. A more complex usage example is in
docs/renderers/QuickHtml_example.php
QuickHtml renderer usage
<?php
require_once 'HTML/QuickForm.php';
require_once 'HTML/QuickForm/Renderer/QuickHtml.php';
// Create form elements and renderer
$form =& new HTML_QuickForm('tmp_form','POST');
$renderer =& new HTML_QuickForm_Renderer_QuickHtml();
// Create a hidden element. Note how we don't render it explicitly,
// rather we let QuickHtml render it for us at the beginning of the form.
$form->addElement('hidden','tmp_hidden');
// Create 2 radio elements. Note how we have to give a value when rendering
// them since that is the only way to tell them apart.
$form->addElement('radio','tmp_radio',null,null,'Y');
$form->addElement('radio','tmp_radio',null,null,'N');
// Create a group with a rule
$text = array();
$text[] =& HTML_QuickForm::createElement('text','',null,array('size' => 3));
$text[] =& HTML_QuickForm::createElement('text','',null,array('size' => 4));
$text[] =& HTML_QuickForm::createElement('text','',null,array('size' => 3));
$form->addGroup($text, 'tmp_phone', null, '-');
$form->addRule('tmp_phone','Phone number cannot be empty.','required',null,'client');
// Do the magic of creating the form. NOTE: order is important here: this must
// be called after creating the form elements, but before rendering them.
$form->accept($renderer);
// Create a very basic template for our form
$html_template = '
<div style="text-align: center; font-weight: bold;">QuickHtml - Basic Example</div>
<div style="text-align: center; background-color: #ccc; margin: 1px;">Phone: %phoneNumber%</div>
<div style="text-align: left; background-color: #ccc; margin: 1px;">Yes: %radioElementYes% No: %radioElementNo%</div>';
// Interpolate the form elements into our template
$html_template = str_replace('%phoneNumber%', $renderer->elementToHtml('tmp_phone'), $html_template);
$html_template = str_replace('%radioElementYes%', $renderer->elementToHtml('tmp_radio', 'Y'), $html_template);
$html_template = str_replace('%radioElementNo%', $renderer->elementToHtml('tmp_radio', 'N'), $html_template);
// The form tags, javascript, and hidden element will be wrapped around
// our html template
echo $renderer->toHtml($html_template);
?>