HTML_QuickForm_Renderer_ITStatic
Description
The word 'static' in renderer name means that exact form layout is defined before the execution of the script starts. That also means that you should have an unique template for each form you want to display with this renderer.
The IT Static renderer, as opposed to the IT Dynamic renderer, offers more flexibility in the way you display your forms but might also takes more time to implement. Therefore, if your form is using always the same pattern to display form element labels and form element html, it is recommended to use the Dynamic renderer. On the other hand, if you have many different layouts for your form elements, for example if you alternate text and form elements, you will prefer to use the Static renderer.
Usage example
With the ITStatic renderer, you have to know beforehand which elements (or group of elements) will compose your form. So we will start by defining our elements.
Defining the elements
<?php
require_once ("HTML/QuickForm.php");
$form = new HTML_QuickForm('myform', 'POST');
$form->addElement('header', 'myheader', 'Registration form');
$form->addElement('hidden', 'session', '123456');
$name['last'] = &HTML_QuickForm::createElement('text', 'first', 'First', array('size' => 10));
$name['first'] = &HTML_QuickForm::createElement('text', 'last', 'Last', array('size' => 10));
$form->addGroup($name, 'name', 'Name:', '-');
$form->addElement('text', 'email', 'Your email:');
$select = array('' => 'Please select...',
'AU' => 'Australia',
'FR' => 'France',
'DE' => 'Germany',
'IT' => 'Italy');
$form->addElement('select', 'country', 'Country:', $select);
$form->addElement('reset', 'reset', 'Reset');
$form->addElement('submit', 'submit', 'Register');
$form->addElement('checkbox', 'news', '', " Check this box if you don't want to receive our newsletter.");
?>
Now our form contains these elements:
One header: 'Registration form'
One hidden field
One group of two textfields: firstname and lastname
One textfield for the E-Mail address
One selectbox for the country with an empty default value
Two buttons: Reset and Register
One checkbox to subscribe to the newsletter
Now that we know which elements compose our form, it will be easy to layout the form
using a WYSIWYG or an HTML editor. The idea is to use placeholders instead of labels
and element html. The placeholders are named after the form and element or group
names: formName_elementName or formName_groupName_elementName. Then
you add _label or _html. We will save the following code in a
template.html file.
A template
<html>
<head><title>My Form</title>
{myform_javascript}
</head>
<body>
<form {myform_attributes}>
{myform_session_html}
<table>
<tr><th colspan="2">{myform_myheader}</th></tr>
<tr><td>{myform_name_label}</td><td>{myform_name_html}</td></tr>
<tr><td>{myform_email_label}</td><td>{myform_email_html}</td></tr>
<tr><td>{myform_country_label}</td><td>{myform_country_html}</td></tr>
<tr><td colspan="2" align="right">{myform_reset_html} {myform_submit_html}</td></tr>
</table>
<br /><br />
{myform_news_html}
</form>
</body>
</html>
As you can notice, the layout is static. This makes the Static renderer only useful if
your form does not change on runtime. Nevertheless, you can still hide blocks if you
use the removeEmptyBlocks option of
HTML_Template_IT /
HTML_Template_Sigma.
Now that we have the elements and the template, we are going to use our Static renderer.
Using the renderer
<?php
require_once 'HTML/Template/Sigma.php';
require_once 'HTML/QuickForm/Renderer/ITStatic.php';
$tpl =& new HTML_Template_Sigma('.');
$tpl->loadTemplateFile('template.html'); // or whatever you called it
$renderer =& new HTML_QuickForm_Renderer_ITStatic($tpl);
$renderer->setRequiredTemplate('{label}<font color="red" size="1">*</font>');
$renderer->setErrorTemplate('<font color="red">{error}</font><br />{html}');
$form->accept($renderer);
$tpl->show();
?>
You can optionally specify the way your required elements and validation errors are
rendered using respectively setRequiredTemplate() and
setErrorTemplate(). In the given string, you will place either the
{label} or the {html} placeholder at
the position you want. If you prefer to have all your errors displayed at the same
place, pass an empty string to setErrorTemplate() and add this
block to your template at the position you want:
<!-- BEGIN myform_error_loop -->
<font color="red">{myform_error}</font><br />
<!-- END myform_error_loop -->
With the Static renderer, it is also possible to customize the way your groups are rendered. If you simply use a placeholder for your whole group, the group will be rendered using HTML_QuickForm default renderer. This means that if a separator string (or an array of separators) was specified, it will be used the usual way. In our form, the group called 'name' was rendered this way, using a - to separate the elements.
The problem we have is that elements inside the group don't show their label, so it is not possible to guess which textfield is firstname and which one is lastname. By replacing the layout for the element 'name' by these new placeholders, can customize the way the group will be displayed:
(...)
<tr>
<td>{myform_name_label}</td>
<td>
<!-- BEGIN myform_name_error -->{myform_name_error}<!-- END myform_name_error -->
<table>
<tr><td>{myform_name_first_html}</td><td>{myform_name_last_html}</td></tr>
<tr><td>{myform_name_first_label}</td><td>{myform_name_last_label}</td></tr>
</table>
</td>
</tr>
(...)
We need to add a new block and placeholder to let the renderer know where to display the error relative to this group. As you have noticed, every placeholder take the name of his group along with its own name.
Also note that if you use elements with the same name, like radios that are not in a group, you will have to add an index to the placeholder name starting at 0, like this:
{myform_myradio_0_html},{myform_myradio_1_html}...
We have seen how to use the Static renderer with standard elements and groups of
elements. We have seen how to display errors and required tags. They won't show in your
form because we did not add any validation rules. Feel free to try to add them as an
exercise. You can also add a special placeholder to your template
{myform_required_note}, it will display the note that indicates
how to find required elements. This renderer usage is very easy, when you feel
comfortable with it, you can move on to the Dynamic renderer which might also fit your
needs in an other way.