repo_zf1/documentation/manual/en/module_specs/Zend_Dojo-View-Helpers.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect2 id="zend.dojo.view.dijit">
    <title>Dijit-Specific View Helpers</title>

    <para>
        From the Dojo manual: "Dijit is a widget system layered on top of
        dojo." Dijit includes a variety of layout and form widgets designed to
        provide accessibility features, localization, and standardized (and
        themeable) look-and-feel.
    </para>

    <para>
        Zend Framework ships a variety of view helpers that allow you to render
        and utilize dijits within your view scripts. There are three basic
        types:
    </para>

    <itemizedlist>
        <listitem>
            <para>
                <emphasis>Layout Containers</emphasis>: these are designed to be
                used within your view scripts or consumed by form decorators
                for forms, sub forms, and display groups. They wrap the various
                classes offerred in dijit.layout. Each dijit layout view helper
                expects the following arguments:
            </para>

            <itemizedlist>
                <listitem><para>
                        <varname>$id</varname>: the container name or DOM ID.
                </para></listitem>

                <listitem><para>
                        <varname>$content</varname>: the content to wrap in the
                        layout container.
                </para></listitem>

                <listitem><para>
                        <varname>$params</varname> (optional): dijit-specific
                        parameters. Basically, any non-HTML attribute that can
                        be used to configure the dijit layout container.
                </para></listitem>

                <listitem><para>
                        <varname>$attribs</varname> (optional): any additional HTML
                        attributes that should be used to render the container
                        div. If the key 'id' is passed in this array, it will
                        be used for the form element DOM id, and
                        <varname>$id</varname> will be used for its name.
                </para></listitem>
            </itemizedlist>

            <para>
                If you pass no arguments to a dijit layout view helper, the
                helper itself will be returned. This allows you to capture
                content, which is often an easier way to pass content to the
                layout container. Examples of this functionality will be shown
                later in this section.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis>Form Dijit</emphasis>: the dijit.form.Form dijit, while
                not completely necessary for use with dijit form elements, will
                ensure that if an attempt is made to submit a form that does
                not validate against client-side validations, submission will
                be halted and validation error messages raised. The form dijit
                view helper expects the following arguments:
            </para>

            <itemizedlist>
                <listitem><para>
                        <varname>$id</varname>: the container name or DOM ID.
                </para></listitem>

                <listitem><para>
                        <varname>$attribs</varname> (optional): any additional HTML
                        attributes that should be used to render the container
                        div.
                </para></listitem>

                <listitem><para>
                        <varname>$content</varname> (optional): the content to wrap
                        in the form. If none is passed, an empty string will be
                        used.
                </para></listitem>
            </itemizedlist>

            <para>
                The argument order varies from the other dijits in order to
                keep compatibility with the standard <methodname>form()</methodname> view
                helper.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis>Form Elements</emphasis>: these are designed to be
                consumed with <classname>Zend_Form</classname>, but can be used
                standalone within view scripts as well. Each dijit element view
                helper expects the following arguments:
            </para>

            <itemizedlist>
                <listitem><para>
                        <varname>$id</varname>: the element name or DOM ID.
                </para></listitem>

                <listitem><para>
                        <varname>$value</varname> (optional): the current value of
                        the element.
                </para></listitem>

                <listitem><para>
                        <varname>$params</varname> (optional): dijit-specific
                        parameters. Basically, any non-HTML attribute that can
                        be used to configure a dijit.
                </para></listitem>

                <listitem><para>
                        <varname>$attribs</varname> (optional): any additional HTML
                        attributes that should be used to render the dijit. If
                        the key 'id' is passed in this array, it will be used
                        for the form element DOM id, and <varname>$id</varname> will
                        be used for its name.
                </para></listitem>
            </itemizedlist>

            <para>
                Some elements require more arguments; these will be noted with
                the individual element helper descriptions.
            </para>
        </listitem>
    </itemizedlist>

    <para>
        In order to utilize these view helpers, you need to register the path
        to the dojo view helpers with your view object.
    </para>

    <example id="zend.dojo.view.dijit.prefixpath">
        <title>Registering the Dojo View Helper Prefix Path</title>

        <programlisting language="php"><![CDATA[
$view->addHelperPath('Zend/Dojo/View/Helper', 'Zend_Dojo_View_Helper');
]]></programlisting>
    </example>

    <sect3 id="zend.dojo.view.dijit.layout">
        <title>Dijit Layout Elements</title>

        <para>
            The dijit.layout family of elements are for creating custom,
            predictable layouts for your site. For any questions on general
            usage, <ulink
                url="http://dojotoolkit.org/book/dojo-book-0-9/part-2-dijit/layout">read
            more about them in the Dojo manual</ulink>.
        </para>

        <para>
            All dijit layout elements have the
            signature <command>string ($id = null, $content = '', array $params =
                array(), array $attribs = array())</command>. In all caess, if you
            pass no arguments, the helper object itself will be returned. This
            gives you access to the <methodname>captureStart()</methodname> and
            <methodname>captureEnd()</methodname> methods, which allow you to capture
            content instead of passing it to the layout container.
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis>AccordionContainer</emphasis>:
                    dijit.layout.AccordionContainer. Stack all panes together
                    vertically; clicking on a pane titlebar will expand and
                    display that particular pane.
                </para>

                <programlisting language="php"><![CDATA[
<?php echo $view->accordionContainer(
    'foo',
    $content,
    array(
        'duration' => 200,
    ),
    array(
        'style' => 'width: 200px; height: 300px;',
    ),
); ?>
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    <emphasis>AccordionPane</emphasis>: dijit.layout.AccordionPane.
                    For use within AccordionContainer.
                </para>

                <programlisting language="php"><![CDATA[
<?php echo $view->accordionPane(
    'foo',
    $content,
    array(
        'title' => 'Pane Title',
    ),
    array(
        'style' => 'background-color: lightgray;',
    ),
); ?>
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    <emphasis>BorderContainer</emphasis>:
                    dijit.layout.BorderContainer. Achieve layouts with
                    optionally resizable panes such as you might see in a
                    traditional application.
                </para>

                <programlisting language="php"><![CDATA[
<?php echo $view->borderContainer(
    'foo',
    $content,
    array(
        'design' => 'headline',
    ),
    array(
        'style' => 'width: 100%; height: 100%',
    ),
); ?>
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    <emphasis>ContentPane</emphasis>: dijit.layout.ContentPane. Use
                    inside any container except AccordionContainer.
                </para>

                <programlisting language="php"><![CDATA[
<?php echo $view->contentPane(
    'foo',
    $content,
    array(
        'title'  => 'Pane Title',
        'region' => 'left',
    ),
    array(
        'style' => 'width: 120px; background-color: lightgray;',
    ),
); ?>
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    <emphasis>SplitContainer</emphasis>:
                    dijit.layout.SplitContainer. Allows resizable content
                    panes; deprecated in Dojo in favor of BorderContainer.
                </para>

                <programlisting language="php"><![CDATA[
<?php echo $view->splitContainer(
    'foo',
    $content,
    array(
        'orientation'  => 'horizontal',
        'sizerWidth'   => 7,
        'activeSizing' => true,
    ),
    array(
        'style' => 'width: 400px; height: 500px;',
    ),
); ?>
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    <emphasis>StackContainer</emphasis>:
                    dijit.layout.StackContainer. All panes within a
                    StackContainer are placed in a stack; build buttons or
                    functionality to reveal one at a time.
                </para>

                <programlisting language="php"><![CDATA[
<?php echo $view->stackContainer(
    'foo',
    $content,
    array(),
    array(
        'style' => 'width: 400px; height: 500px; border: 1px;',
    ),
); ?>
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    <emphasis>TabContainer</emphasis>:
                    dijit.layout.TabContainer. All panes within a
                    TabContainer are placed in a stack, with tabs positioned on
                    one side for switching between them.
                </para>

                <programlisting language="php"><![CDATA[
<?php echo $view->tabContainer(
    'foo',
    $content,
    array(),
    array(
        'style' => 'width: 400px; height: 500px; border: 1px;',
    ),
); ?>
]]></programlisting>
            </listitem>
        </itemizedlist>

        <para>
            The following capture methods are available for all layout
            containers:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <command>captureStart($id, array $params = array(), array $attribs =
                        array())</command>: begin capturing content to include in a container.
                    <varname>$params</varname> refers to the dijit params to use with
                    the container, while <varname>$attribs</varname> refer to any
                    general HTML attributes to use.
                </para>

                <para>
                    Containers may be nested when capturing, <emphasis>so long
                    as no ids are duplicated</emphasis>.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>captureEnd($id)</methodname>:
                    finish capturing content to include in a container.
                    <varname>$id</varname> should refer to an id previously used with
                    a <methodname>captureStart()</methodname> call. Returns a string
                    representing the container and its contents, just as if
                    you'd simply passed content to the helper itself.
                </para>
            </listitem>
        </itemizedlist>

        <example id="zend.dojo.view.dijit.layout.borderexample">
            <title>BorderContainer layout dijit example</title>

            <para>
                BorderContainers, particularly when coupled with the ability to
                capture content, are especially useful for achieving complex
                layout effects.
            </para>

            <programlisting language="php"><![CDATA[
$view->borderContainer()->captureStart('masterLayout',
                                       array('design' => 'headline'));

echo $view->contentPane(
    'menuPane',
    'This is the menu pane',
    array('region' => 'top'),
    array('style' => 'background-color: darkblue;')
);

echo  $view->contentPane(
    'navPane',
    'This is the navigation pane',
    array('region' => 'left'),
    array('style' => 'width: 200px; background-color: lightblue;')
);

echo $view->contentPane(
    'mainPane',
    'This is the main content pane area',
    array('region' => 'center'),
    array('style' => 'background-color: white;')
);

echo $view->contentPane(
    'statusPane',
    'Status area',
    array('region' => 'bottom'),
    array('style' => 'background-color: lightgray;')
);

echo $view->borderContainer()->captureEnd('masterLayout');
]]></programlisting>
        </example>
    </sect3>

    <sect3 id="zend.dojo.view.dijit.form">
        <title>Dijit Form Elements</title>

        <para>
            Dojo's form validation and input dijits are in the dijit.form tree.
            For more information on general usage of these elements, as well as
            accepted parameters, please <ulink
                url="http://dojotoolkit.org/book/dojo-book-0-9/part-2-dijit/form-validation-specialized-input">visit
                the dijit.form documentation</ulink>.
        </para>

        <para>
            The following dijit form elements are available in Zend Framework.
            Except where noted, all have the signature <command>string ($id,
                $value = '', array $params = array(), array $attribs =
                array())</command>.
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis>Button</emphasis>: dijit.form.Button. Display a
                    form button.
                </para>

                <programlisting language="php"><![CDATA[
<?php echo $view->button(
    'foo',
    'Show Me!',
    array('iconClass' => 'myButtons'),
); ?>
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    <emphasis>CheckBox</emphasis>:
                    dijit.form.CheckBox. Display a checkbox. Accepts an
                    optional fifth argument, the array
                    <varname>$checkedOptions</varname>, which may contain either:
                </para>

                <itemizedlist>
                    <listitem><para>
                            an indexed array with two values, a checked value
                            and unchecked value, in that order; or
                    </para></listitem>

                    <listitem><para>
                            an associative array with the keys 'checkedValue'
                            and 'unCheckedValue'.
                    </para></listitem>
                </itemizedlist>

                <para>
                    If <varname>$checkedOptions</varname> is not provided, 1 and 0
                    are assumed.
                </para>

                <programlisting language="php"><![CDATA[
<?php echo $view->checkBox(
    'foo',
    'bar',
    array(),
    array(),
    array('checkedValue' => 'foo', 'unCheckedValue' => 'bar')
); ?>
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    <emphasis>ComboBox</emphasis>:
                    dijit.layout.ComboBox. ComboBoxes are a hybrid between a
                    select and a text box with autocompletion. The key
                    difference is that you may type an option that is not in
                    the list of available options, and it will still consider
                    it valid input. It accepts an optional fifth argument, an
                    associative array <varname>$options</varname>; if provided,
                    ComboBox will be rendered as a <emphasis>select</emphasis>. Note
                    also that the <emphasis>label values</emphasis> of the
                    <varname>$options</varname> array will be returned in the form --
                    not the values themselves.
                </para>

                <para>
                    Alternately, you may pass information regarding a dojo.data
                    datastore to use with the element. If provided, the
                    ComboBox will be rendered as a text <emphasis>input</emphasis>, and
                    will pull its options via that datastore.
                </para>

                <para>
                    To specify a datastore, provide one of the following
                    <varname>$params</varname> key combinations:
                </para>

                <itemizedlist>
                    <listitem>
                        <para>
                            The key 'store', with an array value; the array
                            should contain the keys:
                        </para>

                        <itemizedlist>
                            <listitem><para>
                                <emphasis>store</emphasis>: the name of the
                                javascript variable representing the datastore
                                (this could be the name you would like for it
                                to use).
                            </para></listitem>

                            <listitem><para>
                                <emphasis>type</emphasis>: the datastore type
                                to use; e.g., 'dojo.data.ItemFileReadStore'.
                            </para></listitem>

                            <listitem><para>
                                <emphasis>params</emphasis> (optional): an
                                associative array of key/value pairs to use to
                                configure the datastore. The 'url' param is a
                                typical example.
                            </para></listitem>
                        </itemizedlist>
                    </listitem>

                    <listitem>
                        <para>
                            The keys:
                        </para>

                        <itemizedlist>
                            <listitem><para>
                                <emphasis>store</emphasis>: a string indicating
                                the datastore name to use.
                            </para></listitem>

                            <listitem><para>
                                <emphasis>storeType</emphasis>: a string indicating
                                the datastore dojo.data type to use (e.g.,
                                'dojo.data.ItemFileReadStore').
                            </para></listitem>

                            <listitem><para>
                                <emphasis>storeParams</emphasis>: an
                                associative array of key/value pairs with which
                                to configure the datastore.
                            </para></listitem>
                        </itemizedlist>
                    </listitem>
                </itemizedlist>

                <programlisting language="php"><![CDATA[
// As a select element:
echo $view->comboBox(
    'foo',
    'bar',
    array(
        'autocomplete' => false,
    ),
    array(),
    array(
        'foo' => 'Foo',
        'bar' => 'Bar',
        'baz' => 'Baz',
    )
);

// As a dojo.data-enabled element:
echo $view->comboBox(
    'foo',
    'bar',
    array(
        'autocomplete' => false,
        'store'        => 'stateStore',
        'storeType'    => 'dojo.data.ItemFileReadStore',
        'storeParams'  => array('url' => '/js/states.json'),
    ),
);
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    <emphasis>CurrencyTextBox</emphasis>:
                    dijit.form.CurrencyTextBox. Inherits from
                    ValidationTextBox, and provides client-side validation of
                    currency. It expects that the dijit parameter 'currency'
                    will be provided with an appropriate 3-character currency
                    code. You may also specify any dijit parameters valid for
                    ValidationTextBox and TextBox.
                </para>

                <programlisting language="php"><![CDATA[
echo $view->currencyTextBox(
    'foo',
    '$25.00',
    array('currency' => 'USD'),
    array('maxlength' => 20)
);
]]></programlisting>

                <note>
                    <title>Issues with Builds</title>

                    <para>
                        There are currently <ulink
                            url="http://trac.dojotoolkit.org/ticket/7183">known
                        issues with using CurrencyTextBox with build
                        layers</ulink>. A known work-around is to ensure that
                        your document's Content-Type http-equiv meta tag sets the
                        character set to utf-8, which you can do by calling:
                    </para>

                    <programlisting language="php"><![CDATA[
$view->headMeta()->appendHttpEquiv('Content-Type',
                                   'text/html; charset=utf-8');
]]></programlisting>

                    <para>
                        This will mean, of course, that you will need to ensure
                        that the <methodname>headMeta()</methodname> placeholder is echoed
                        in your layout script.
                    </para>
                </note>
            </listitem>

            <listitem>
                <para>
                    <emphasis>DateTextBox</emphasis>:
                    dijit.form.DateTextBox. Inherits from
                    ValidationTextBox, and provides both client-side validation of
                    dates, as well as a dropdown calendar from which to select a date.
                    You may specify any dijit parameters available to
                    ValidationTextBox or TextBox.
                </para>

                <programlisting language="php"><![CDATA[
echo $view->dateTextBox(
    'foo',
    '2008-07-11',
    array('required' => true)
);
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    <emphasis>Editor</emphasis>: dijit.Editor. Provides a
                    WYSIWYG editor via which users may create or edit content.
                    <command>dijit.Editor</command> is a pluggable, extensible editor
                    with a variety of parameters you can utilize for customization; see <ulink
                        url="http://dojotoolkit.org/book/dojo-book-0-9/part-2-dijit/advanced-editing-and-display/editor-rich-text">the
                        dijit.Editor documentation</ulink> for more details.
                </para>

                <programlisting language="php"><![CDATA[
echo $view->editor('foo');
]]></programlisting>

                <note>
                    <title>Editor Dijit uses div by default</title>

                    <para>
                        The Editor dijit uses an <acronym>HTML</acronym> <acronym>DIV</acronym> by
                        default. The <classname>dijit._editor.RichText</classname> <ulink
                            url="http://api.dojotoolkit.org/jsdoc/HEAD/dijit._editor.RichText">documentation</ulink>
                        indicates that having it built on an HTML <acronym>TEXTAREA</acronym> can
                        potentially have security implications.
                    </para>

                    <para>
                        In order to allow graceful degradation in environments where Javascript is
                        unavailable, <classname>Zend_Dojo_View_Helper_Editor</classname> also wraps
                        a <acronym>textarea</acronym> within a <acronym>noscript</acronym> tag; the
                        content of this <acronym>textarea</acronym> will be properly escaped to
                        avoid security vulnerability vectors.
                    </para>
                </note>
            </listitem>

            <listitem>
                <para>
                    <emphasis>FilteringSelect</emphasis>:
                    dijit.form.FilteringSelect. Similar to ComboBox, this is a
                    select/text hybrid that can either render a provided list
                    of options or those fetched via a dojo.data datastore.
                    Unlike ComboBox, however, FilteringSelect does not allow
                    typing in an option not in its list. Additionally, it
                    operates like a standard select in that the option values,
                    not the labels, are returned when the form is submitted.
                </para>

                <para>
                    Please see the information above on ComboBox for examples
                    and available options for defining datastores.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>HorizontalSlider</emphasis> and
                    <emphasis>VerticalSlider</emphasis>:
                    dijit.form.HorizontalSlider and dijit.form.VerticalSlider.
                    Sliders allow are UI widgets for selecting numbers in a
                    given range; these are horizontal and vertical variants.
                </para>

                <para>
                    At their most basic, they require the dijit parameters
                    'minimum', 'maximum', and 'discreteValues'. These define
                    the range of values. Other common options are:
                </para>

                <itemizedlist>
                    <listitem><para>
                        'intermediateChanges' can be set to indicate whether or not
                        to fire onChange events while the handle is being dragged.
                    </para></listitem>

                    <listitem><para>
                        'clickSelect' can be set to allow clicking a location
                        on the slider to set the value.
                    </para></listitem>

                    <listitem><para>
                        'pageIncrement' can specify the value by which to
                        increase/decrease when pageUp and pageDown are used.
                    </para></listitem>

                    <listitem><para>
                        'showButtons' can be set to allow displaying buttons on
                        either end of the slider for manipulating the value.
                    </para></listitem>
                </itemizedlist>

                <para>
                    The Zend Framework implementation creates a hidden element
                    to store the value of the slider.
                </para>

                <para>
                    You may optionally desire to show a rule or labels for the
                    slider. To do so, you will assign one or more of the dijit
                    params 'topDecoration' and/or 'bottomDecoration'
                    (HorizontalSlider) or 'leftDecoration' and/or
                    'rightDecoration' (VerticalSlider). Each of these expects
                    the following options:
                </para>

                <itemizedlist>
                    <listitem><para>
                        <emphasis>container</emphasis>: name of the container.
                    </para></listitem>

                    <listitem><para>
                        <emphasis>labels</emphasis> (optional): an array of
                        labels to utilize. Use empty strings on either end to
                        provide labels for inner values only. Required when
                        specifying one of the 'Labels' dijit variants.
                    </para></listitem>

                    <listitem><para>
                        <emphasis>dijit</emphasis> (optional): one of
                        HorizontalRule, HorizontalRuleLabels, VerticalRule, or
                        VerticalRuleLabels, Defaults to one of the Rule dijits.
                    </para></listitem>

                    <listitem>
                        <para>
                            <emphasis>params</emphasis> (optional): dijit params
                            for configuring the Rule dijit in use. Parameters
                            specific to these dijits include:
                        </para>

                        <itemizedlist>
                            <listitem><para>
                                <emphasis>container</emphasis> (optional):
                                array of parameters and attributes for the rule
                                container.
                            </para></listitem>

                            <listitem><para>
                                <emphasis>labels</emphasis> (optional):
                                array of parameters and attributes for the
                                labels list container.
                            </para></listitem>
                        </itemizedlist>
                    </listitem>

                    <listitem><para>
                        <emphasis>attribs</emphasis> (optional): HTML
                        attributes to use with the rules/labels. This should
                        follow the <property>params</property> option format and be an
                        associative array with the keys 'container' and
                        'labels'.
                    </para></listitem>
                </itemizedlist>

                <programlisting language="php"><![CDATA[
echo $view->horizontalSlider(
    'foo',
    1,
    array(
        'minimum'             => -10,
        'maximum'             => 10,
        'discreteValues'      => 11,
        'intermediateChanges' => true,
        'showButtons'         => true,
        'topDecoration'       => array(
            'container' => 'topContainer'
            'dijit'     => 'HorizontalRuleLabels',
            'labels'    => array(
                ' ',
                '20%',
                '40%',
                '60%',
                '80%',
                ' ',
            ),
            'params' => array(
                'container' => array(
                    'style' => 'height:1.2em; font-size=75%;color:gray;',
                ),
                'labels' => array(
                    'style' => 'height:1em; font-size=75%;color:gray;',
                ),
            ),
        ),
        'bottomDecoration'    => array(
            'container' => 'bottomContainer'
            'labels'    => array(
                '0%',
                '50%',
                '100%',
            ),
            'params' => array(
                'container' => array(
                    'style' => 'height:1.2em; font-size=75%;color:gray;',
                ),
                'labels' => array(
                    'style' => 'height:1em; font-size=75%;color:gray;',
                ),
            ),
        ),
    )
);
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    <emphasis>NumberSpinner</emphasis>:
                    dijit.form.NumberSpinner. Text box for numeric entry, with
                    buttons for incrementing and decrementing.
                </para>

                <para>
                    Expects either an associative array for the dijit parameter
                    'constraints', or simply the keys 'min', 'max', and
                    'places' (these would be the expected entries of the
                    constraints parameter as well). 'places' can be used to
                    indicate how much the number spinner will increment and
                    decrement.
                </para>

                <programlisting language="php"><![CDATA[
echo $view->numberSpinner(
    'foo',
    5,
    array(
        'min'    => -10,
        'max'    => 10,
        'places' => 2,
    ),
    array(
        'maxlenth' => 3,
    )
);
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    <emphasis>NumberTextBox</emphasis>:
                    dijit.form.NumberTextBox. NumberTextBox provides the
                    ability to format and display number entries in a localized
                    fashion, as well as validate numerical entries, optionally
                    against given constraints.
                </para>

                <programlisting language="php"><![CDATA[
echo $view->numberTextBox(
    'foo',
    5,
    array(
        'places' => 4,
        'type'   => 'percent',
    ),
    array(
        'maxlength' => 20,
    )
);
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    <emphasis>PasswordTextBox</emphasis>:
                    dijit.form.ValidationTextBox tied to a password input.
                    PasswordTextBox provides the
                    ability to create password input that adheres to the current
                    dijit theme, as well as allow for client-side validation.
                </para>

                <programlisting language="php"><![CDATA[
echo $view->passwordTextBox(
    'foo',
    '',
    array(
        'required' => true,
    ),
    array(
        'maxlength' => 20,
    )
);
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    <emphasis>RadioButton</emphasis>: dijit.form.RadioButton. A
                    set of options from which only one may be selected. This
                    behaves in every way like a regular radio, but has a
                    look-and-feel consistent with other dijits.
                </para>

                <para>
                    RadioButton accepts an optional fifth argument,
                    <varname>$options</varname>, an associative array of value/label
                    pairs used as the radio options. You may also pass these as
                    the <varname>$attribs</varname> key <property>options</property>.
                </para>

                <programlisting language="php"><![CDATA[
echo $view->radioButton(
    'foo',
    'bar',
    array(),
    array(),
    array(
        'foo' => 'Foo',
        'bar' => 'Bar',
        'baz' => 'Baz',
    )
);
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    <emphasis>SimpleTextarea</emphasis>: dijit.form.SimpleTextarea.
                    These act like normal textareas, but are styled using the
                    current dijit theme. You do not need to specify either the
                    rows or columns attributes; use <property>ems</property> or
                    percentages for the width and height, instead.
                </para>

                <programlisting language="php"><![CDATA[
echo $view->simpleTextarea(
    'foo',
    'Start writing here...',
    array(),
    array('style' => 'width: 90%; height: 5ems;')
);
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    <emphasis>SubmitButton</emphasis>: a dijit.form.Button tied
                    to a submit input element. See the Button view helper for
                    more details; the key difference is that this button can
                    submit a form.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>Textarea</emphasis>: dijit.form.Textarea. These
                    act like normal textareas, except that instead of having a
                    set number of rows, they expand as the user types. The
                    width should be specified via a style setting.
                </para>

                <programlisting language="php"><![CDATA[
echo $view->textarea(
    'foo',
    'Start writing here...',
    array(),
    array('style' => 'width: 300px;')
);
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    <emphasis>TextBox</emphasis>: dijit.form.TextBox. This
                    element is primarily present to provide a common
                    look-and-feel between various dijit elements, and to
                    provide base functionality for the other TextBox-derived
                    classes (ValidationTextBox, NumberTextBox, CurrencyTextBox,
                    DateTextBox, and TimeTextBox).
                </para>

                <para>
                    Common dijit parameter flags include 'lowercase' (cast to
                    lowercase), 'uppercase' (cast to UPPERCASE), 'propercase'
                    (cast to Proper Case), and trim (trim leading and trailing
                    whitespace); all accept boolean values. Additionally, you
                    may specifiy the parameters 'size' and 'maxLength'.
                </para>

                <programlisting language="php"><![CDATA[
echo $view->textBox(
    'foo',
    'some text',
    array(
        'trim'       => true,
        'propercase' => true,
        'maxLength'  => 20,
    ),
    array(
        'size' => 20,
    )
);
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    <emphasis>TimeTextBox</emphasis>: dijit.form.TimeTextBox.
                    Also in the TextBox family, TimeTextBox provides a
                    scrollable drop down selection of times from which a user
                    may select. Dijit parameters allow you to specify the time
                    increments available in the select as well as the visible
                    range of times available.
                </para>

                <programlisting language="php"><![CDATA[
echo $view->timeTextBox(
    'foo',
    '',
    array(
        'am.pm'            => true,
        'visibleIncrement' => 'T00:05:00', // 5-minute increments
        'visibleRange'     => 'T02:00:00', // show 2 hours of increments
    ),
    array(
        'size' => 20,
    )
);
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    <emphasis>ValidationTextBox</emphasis>:
                    dijit.form.ValidateTextBox. Provide client-side validations
                    for a text element. Inherits from TextBox.
                </para>

                <para>
                    Common dijit parameters include:
                </para>

                <itemizedlist>
                    <listitem><para>
                        <emphasis>invalidMessage</emphasis>: a message to
                        display when an invalid entry is detected.
                    </para></listitem>

                    <listitem><para>
                        <emphasis>promptMessage</emphasis>: a tooltip help
                        message to use.
                    </para></listitem>

                    <listitem><para>
                        <emphasis>regExp</emphasis>: a regular expression to
                        use to validate the text. Regular expression does not
                        require boundary markers.
                    </para></listitem>

                    <listitem><para>
                        <emphasis>required</emphasis>: whether or not the
                        element is required. If so, and the element is embedded
                        in a dijit.form.Form, it will be flagged as invalid and
                        prevent submission.
                    </para></listitem>
                </itemizedlist>

                <programlisting language="php"><![CDATA[
echo $view->validationTextBox(
    'foo',
    '',
    array(
        'required' => true,
        'regExp'   => '[\w]+',
        'invalidMessage' => 'No spaces or non-word characters allowed',
        'promptMessage'  => 'Single word consisting of alphanumeric ' .
                            'characters and underscores only',
    ),
    array(
        'maxlength' => 20,
    )
);
]]></programlisting>
            </listitem>
        </itemizedlist>
    </sect3>

    <sect3 id="zend.dojo.view.dijit.custom">
        <title>Custom Dijits</title>

        <para>
            If you delve into Dojo much at all, you'll find yourself writing
            custom dijits, or using experimental dijits from Dojox. While Zend
            Framework cannot support every dijit directly, it does provide some
            rudimentary support for arbitrary dijit types via the
            <classname>CustomDijit</classname> view helper.
        </para>

        <para>
            The <classname>CustomDijit</classname> view helper's <acronym>API</acronym> is exactly
            that of any other dijit, with one major difference: the third "params"
            argument <emphasis>must</emphasis> contain the attribute "dojotype".
            The value of this attribute should be the Dijit class you plan to
            use.
        </para>

        <para>
            <classname>CustomDijit</classname> extends the base
            <classname>DijitContainer</classname> view helper, which also allows it to
            capture content (using the
            <methodname>captureStart()</methodname>/<methodname>captureEnd()</methodname> pair of
            methods). <methodname>captureStart()</methodname> also expects that you pass the
            "dojoType" attribute to its "params" argument.
        </para>

        <example id="zend.dojo.view.dijit.custom.example">
            <title>Using CustomDijit to render a dojox.layout.ContentPane</title>

            <para>
                <command>dojox.layout.ContentPane</command> is a next-generation
                iteration of <command>dijit.layout.ContentPane</command>, and provides
                a superset of that class's capabilities. Until it's
                functionality stabilizes, it will continue to live in Dojox.
                However, if you want to use it in Zend Framework today, you can,
                using the <classname>CustomDijit</classname> view helper.
            </para>

            <para>
                At its most basic, you can do the following:
            </para>

            <programlisting language="php"><![CDATA[
<?php echo $this->customDijit(
    'foo',
    $content,
    array(
        'dojoType' => 'dojox.layout.ContentPane',
        'title'    => 'Custom pane',
        'region'   => 'center'
    )
); ?>
]]></programlisting>

            <para>
                If you wanted to capture content instead, simply use the
                <methodname>captureStart()</methodname> method, and pass the "dojoType" to
                the "params" argument:
            </para>

            <programlisting language="php"><![CDATA[
<?php $this->customDijit()->captureStart(
    'foo',
    array(
        'dojoType' => 'dojox.layout.ContentPane',
        'title'    => 'Custom pane',
        'region'   => 'center'
    )
); ?>
This is the content of the pane
<?php echo $this->customDijit()->captureEnd('foo'); ?>
]]></programlisting>

            <para>
                You can also extend <classname>CustomDijit</classname> easily to create
                support for your own custom dijits. As an example, if you
                extended <command>dijit.layout.ContentPane</command> to create your
                own <command>foo.ContentPane</command> class, you could create the
                following helper to support it:
            </para>

            <programlisting language="php"><![CDATA[
class My_View_Helper_FooContentPane
    extends Zend_Dojo_View_Helper_CustomDijit
{
    protected $_defaultDojoType = 'foo.ContentPane';

    public function fooContentPane(
        $id = null, $value = null,
        array $params = array(), array $attribs = array()
    ) {
        return $this->customDijit($id, $value, $params, $attribs);
    }
}
]]></programlisting>

            <para>
                As long as your custom dijit follows the same basic <acronym>API</acronym> as
                official dijits, using or extending <classname>CustomDijit</classname>
                should work correctly.
            </para>
        </example>
    </sect3>
</sect2>
<!--
vim:se ts=4 sw=4 et:
-->