PEAR Справочное руководство
Пред. След.

HTML_QuickForm_Renderer_ITStatic

HTML_QuickForm_Renderer_ITStatic -- Static renderer for Integrated Templates

Описание

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.

Пример 43-1. Defining the elements

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:

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.

Пример 43-2. 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.

Пример 43-3. Using the renderer

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.

Пред. Начало След.
HTML_QuickForm_Renderer_ITDynamic::setHeaderBlock() Уровень выше constructor HTML_QuickForm_Renderer_ITStatic::HTML_QuickForm_Renderer_ITStatic()
    Поддержать сайт на родительском проекте КГБ