PEAR Manual
Prev |  | Next

# HTML_QuickForm_Renderer_ITDynamic

HTML_QuickForm_Renderer_ITDynamic -- Dynamic renderer for Integrated Templates

## Description

The word 'dynamic' in renderer name means that exact form layout is defined at script runtime. This also means that you can create one template file for all your forms. That template should contain a block for every distinct element 'look' appearing in your forms and also some special blocks. If a special block is not set for an element, the renderer falls back to a default one.

If most of your forms tend to share the same look (a good example would be back-office interface), your best bet will be to use Dynamic renderer. If each of your forms has a really special layout, you should go with a Static one.

## Template structure

This is a somewhat minimal template, but it contains all the necessary elements to render any form you are able to define with the package.

    {qf_javascript}
    <form {qf_attributes}>
    <!-- BEGIN qf_hidden_loop -->
    {qf_hidden}
    <!-- END qf_hidden_loop -->

    <table>

    <!-- BEGIN qf_errors -->
        <tr>
            <td>
                Collected errors:
                <ul>
                    <!-- BEGIN qf_error_loop -->
                    <li>{qf_error}</li>
                    <!-- END qf_error_loop -->
                </ul>
            </td>
        </tr>
    <!-- END qf_errors -->

    <!-- BEGIN qf_main_loop -->
        <!-- BEGIN qf_header -->
        <tr>
            <th colspan="2">{qf_header}</th>
        </tr>
        <!-- END qf_header -->

        <!-- BEGIN qf_element -->
        <tr valign="top">
            <td align="right">
                <!-- BEGIN qf_element_required --><span style="color: #FF0000;">*</span><!-- END qf_element_required -->
                <b>{qf_label}</b>
            </td>
            <td>
                <!-- BEGIN qf_element_error --><span style="color: #FF0000;">{qf_error}</span><br /><!-- END qf_element_error -->
                {qf_element}
            </td>
        </tr>
        <!-- END qf_element -->

        <!-- BEGIN qf_group -->
        <tr valign="top">
            <td align="right">
                <!-- BEGIN qf_group_required --><span style="color: #FF0000;">*</span><!-- END qf_group_required -->
                <b>{qf_group_label}</b>
            </td>
            <td>
                <!-- BEGIN qf_group_error --><span style="color: #FF0000;">{qf_error}</span><br /><!-- END qf_group_error -->
                <!-- BEGIN qf_group_loop -->
                    <!-- BEGIN qf_group_element -->{qf_separator}{qf_label}{qf_element}<!-- END qf_group_element -->
                <!-- END qf_group_loop -->
            </td>
        </tr>
        <!-- END qf_group -->

    <!-- END qf_main_loop -->

    <!-- BEGIN qf_required_note -->
        <tr>
            <td>&nbsp;</td>
            <td align="left" valign="top">{qf_required_note}</td>
        </tr>
    <!-- END qf_required_note -->
    </table>
    </form>

Blocks in the template

`qf_main_loop`

  This block should always be present and should be a parent for all visible elements' blocks. It is used to implement "flow", to render elements one after another.

`qf_element`

  This is the default block for rendering form elements. This block should always be present, as the renderer uses the following logic to decide which block to use for an element's output:

  1. If a special block was set for an element, use that

  2. If a block `qf_%element's type%` (e.g. `qf_password`) exists, use that

  3. Use `qf_element`

`qf_element_required`

  The block will be touch'd if an element is required.

`qf_element_error`

  An error associated with an element will be output here.

`qf_header`

  This is the default block used to output headers. Should be present unless you have no headers in your form.

`qf_group`

  Default block to output groups. Should be present unless you do not use grouped elements.

`qf_group_loop`

  An analog of `qf_main_loop`, used to render group's elements one after another. A `%group's block%_loop` should always be present inside `%group's block%`

`qf_group_element`

  A default block to render group's elements, `%group's block%_element` should always be present inside `%group's block%_loop` (for the same reason as the `qf_element` should be present in `qf_main_loop`)

`qf_error_loop`

  This is used to output collected errors for the elements that do not have a `%element's block%_error` block.

`qf_hidden_loop`

  <input type="hidden" /> elements are rendered here.

Placeholders in the template

`{qf_javascript}`

  Javascript for client-side form validation will be output here.

`{qf_required_note}`

  If there are required elements in the form, a note will be output here

## Usage example

Assuming the template is in `./qform.html`:

    <?php
    require_once 'HTML/QuickForm/Renderer/ITDynamic.php';
    require_once 'HTML/Template/Sigma.php';

    // Instantiate the template object and load the template file
    $tpl =& new HTML_Template_Sigma('.');
    $tpl->loadTemplateFile('qform.html');

    // Instantiate the renderer and process the form
    $renderer =& new HTML_QuickForm_Renderer_ITDynamic($tpl);
    $form->accept($renderer);

    // Output the results
    $tpl->show();
    ?>

Note that we do not show how the form is built here, that's because the example will work for virtually any form.

> Template class compatibility: This renderer was developed and tested using HTML_Template_Sigma. While it probably will work with HTML_Template_IT, no warranties can be given.

> Removing empty blocks: The renderer assumes that the template object was set up to remove empty blocks (this is the default behaviour). If that is not true, the results will be pretty discouraging.

Prev | Home | Next
HTML_QuickForm_Renderer_ArraySmarty::setRequiredTemplate() | Up | constructor HTML_QuickForm_Renderer_ITDynamic::HTML_QuickForm_Renderer_ITDynamic()