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 <command>dijit.layout</command>. Each dijit layout view helper
                expects the following arguments:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <varname>$id</varname>: the container name or <acronym>DOM</acronym> 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
                        <acronym>HTML</acronym> 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 <acronym>DOM</acronym> 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 <command>dijit.form.Form</command> 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 <acronym>DOM</acronym> ID.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <varname>$attribs</varname> (optional): any additional
                        <acronym>HTML</acronym> 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 <acronym>DOM</acronym> 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
                        <acronym>HTML</acronym> 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 <acronym>DOM</acronym> 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 <command>dijit.layout</command> family of elements are for creating custom,
            predictable layouts for your site. For any questions on general
            usage, <ulink
                url="http://dojotoolkit.org/reference-guide/dijit/layout.html">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>:
                    <command>dijit.layout.AccordionContainer</command>. 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>:
                    <command>dijit.layout.AccordionPane</command>. 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>:
                    <command>dijit.layout.BorderContainer</command>. 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>: <command>dijit.layout.ContentPane</command>.
                    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>:
                    <command>dijit.layout.SplitContainer</command>. 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>:
                    <command>dijit.layout.StackContainer</command>. 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>:
                    <command>dijit.layout.TabContainer</command>. 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 <acronym>HTML</acronym> 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 <command>dijit.form</command> tree.
            For more information on general usage of these elements, as well as
            accepted parameters, please <ulink
                url="http://dojotoolkit.org/reference-guide/dijit/form.html">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>: <command>dijit.form.Button</command>. 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>:
                    <command>dijit.form.CheckBox</command>. 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>:
                    <command>dijit.layout.ComboBox</command>. 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 <command>dojo.data</command>
                    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., '<command>dojo.data.ItemFileReadStore</command>'.
                                </para>
                            </listitem>

                            <listitem>
                                <para>
                                    <emphasis>params</emphasis> (optional): an
                                    associative array of key and 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 <command>dojo.data</command> type to use (e.g.,
                                    '<command>dojo.data.ItemFileReadStore</command>').
                                </para>
                            </listitem>

                            <listitem>
                                <para>
                                    <emphasis>storeParams</emphasis>: an
                                    associative array of key and 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>:
                    <command>dijit.form.CurrencyTextBox</command>. 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>:
                    <command>dijit.form.DateTextBox</command>. 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>: <command>dijit.Editor</command>. Provides a
                    <acronym>WYSIWYG</acronym> 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/reference-guide/dijit/Editor.html">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 <command>dijit._editor.RichText</command> <ulink
                            url="http://api.dojotoolkit.org/jsdoc/HEAD/dijit._editor.RichText">documentation</ulink>
                        indicates that having it built on an <acronym>HTML</acronym>
                        <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>:
                    <command>dijit.form.FilteringSelect</command>. Similar to ComboBox, this is a
                    select and text hybrid that can either render a provided list
                    of options or those fetched via a <command>dojo.data</command> 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>:
                    <command>dijit.form.HorizontalSlider</command> and
                    <command>dijit.form.VerticalSlider</command>. 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 or 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 implication from Zend Framework 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): <acronym>HTML</acronym>
                            attributes to use with the rules and 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>:
                    <command>dijit.form.NumberSpinner</command>. 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>:
                    <command>dijit.form.NumberTextBox</command>. 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>:
                    <command>dijit.form.ValidationTextBox</command> 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>: <command>dijit.form.RadioButton</command>. 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 and 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>:
                    <command>dijit.form.SimpleTextarea</command>. 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 <command>dijit.form.Button</command> 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>: <command>dijit.form.Textarea</command>. 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>: <command>dijit.form.TextBox</command>. 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 <acronym>UPPERCASE</acronym>), '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>: <command>dijit.form.TimeTextBox</command>.
                    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>:
                    <command>dijit.form.ValidateTextBox</command>. 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 <command>dijit.form.Form</command>, 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:
-->