repo_zf1/documentation/manual/en/module_specs/Zend_Dojo-Form-Elements.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect2 id="zend.dojo.form.elements">
    <title>Dijit-Specific Form Elements</title>

    <para>
        Each form dijit for which a view helper is provided has a corresponding
        <classname>Zend_Form</classname> element. All of them have the following methods
        available for manipulating dijit parameters:
    </para>

    <itemizedlist>
        <listitem><para>
                <methodname>setDijitParam($key, $value)</methodname>: set a single dijit
                parameter. If the dijit parameter already exists, it will be
                overwritten.
        </para></listitem>

        <listitem><para>
                <methodname>setDijitParams(array $params)</methodname>: set several dijit
                parameters at once. Any passed parameters matching those
                already present will overwrite.
        </para></listitem>

        <listitem><para>
                <methodname>hasDijitParam($key)</methodname>: If a given dijit parameter
                is defined and present, return TRUE, otherwise return FALSE.
        </para></listitem>

        <listitem><para>
                <methodname>getDijitParam($key)</methodname>: retrieve the given dijit
                parameter. If not available, a null value is returned.
        </para></listitem>

        <listitem><para>
                <methodname>getDijitParams()</methodname>: retrieve all dijit parameters.
        </para></listitem>

        <listitem><para>
                <methodname>removeDijitParam($key)</methodname>: remove the given dijit
                parameter.
        </para></listitem>

        <listitem><para>
                <methodname>clearDijitParams()</methodname>: clear all currently defined
                dijit parameters.
        </para></listitem>
    </itemizedlist>

    <para>
        Dijit parameters are stored in the <code>dijitParams</code> public
        property. Thus, you can dijit-enable an existing form element simply by
        setting this property on the element; you simply will not have the
        above accessors to facilitate manipulating the parameters.
    </para>

    <para>
        Additionally, dijit-specific elements implement a different list of
        decorators, corresponding to the following:
    </para>

    <programlisting language="php"><![CDATA[
$element->addDecorator('DijitElement')
        ->addDecorator('Errors')
        ->addDecorator('HtmlTag', array('tag' => 'dd'))
        ->addDecorator('Label', array('tag' => 'dt'));
]]></programlisting>

    <para>
        In effect, the DijitElement decorator is used in place of the standard
        ViewHelper decorator.
    </para>

    <para>
        Finally, the base Dijit element ensures that the Dojo view helper path
        is set on the view.
    </para>

    <para>
        A variant on DijitElement, DijitMulti, provides the functionality of
        the <code>Multi</code> abstract form element, allowing the developer to
        specify 'multiOptions' -- typically select options or radio options.
    </para>

    <para>
        The following dijit elements are shipped in the standard Zend
        Framework distribution.
    </para>

    <sect3 id="zend.dojo.form.elements.button">
        <title>Button</title>

        <para>
            While not deriving from <link
                linkend="zend.form.standardElements.button">the standard Button
                element</link>, it does implement the same functionality, and
            can be used as a drop-in replacement for it. The following
            functionality is exposed:
        </para>

        <itemizedlist>
            <listitem><para>
                <methodname>getLabel()</methodname> will utilize the element name as the
                button label if no name is provided. Additionally, it will
                translate the name if a translation adapter with a matching
                translation message is available.
            </para></listitem>

            <listitem><para>
                <methodname>isChecked()</methodname> determines if the value submitted
                matches the label; if so, it returns true. This is useful for
                determining which button was used when a form was submitted.
            </para></listitem>
        </itemizedlist>

        <para>
            Additionally, only the decorators <code>DijitElement</code> and
            <code>DtDdWrapper</code> are utilized for Button elements.
        </para>

        <example id="zend.dojo.form.elements.button.example">
            <title>Example Button dijit element usage</title>

            <programlisting language="php"><![CDATA[
$form->addElement(
    'Button',
    'foo',
    array(
        'label' => 'Button Label',
    )
);
]]></programlisting>
        </example>
    </sect3>

    <sect3 id="zend.dojo.form.elements.checkBox">
        <title>CheckBox</title>

        <para>
            While not deriving from <link
                linkend="zend.form.standardElements.checkbox">the standard
                Checkbox element</link>, it does implement the same
            functionality. This means that the following methods are exposed:
        </para>

        <itemizedlist>
            <listitem><para>
                <methodname>setCheckedValue($value)</methodname>: set the value to use when
                the element is checked.
            </para></listitem>

            <listitem><para>
                <methodname>getCheckedValue()</methodname>: get the value of the item to
                use when checked.
            </para></listitem>

            <listitem><para>
                <methodname>setUncheckedValue($value)</methodname>: set the value of the
                item to use when it is unchecked.
            </para></listitem>

            <listitem><para>
                <methodname>getUncheckedValue()</methodname>: get the value of the item to
                use when it is unchecked.
            </para></listitem>

            <listitem><para>
                <methodname>setChecked($flag)</methodname>: mark the element as checked or
                unchecked.
            </para></listitem>

            <listitem><para>
                <methodname>isChecked()</methodname>: determine if the element is currently
                checked.
            </para></listitem>
        </itemizedlist>

        <example id="zend.dojo.form.elements.checkBox.example">
            <title>Example CheckBox dijit element usage</title>

            <programlisting language="php"><![CDATA[
$form->addElement(
    'CheckBox',
    'foo',
    array(
        'label'          => 'A check box',
        'checkedValue'   => 'foo',
        'uncheckedValue' => 'bar',
        'checked'        => true,
    )
);
]]></programlisting>
        </example>
    </sect3>

    <sect3 id="zend.dojo.form.elements.comboBox">
        <title>ComboBox and FilteringSelect</title>

        <para>
            As noted in the ComboBox <link
                linkend="zend.dojo.view.dijit.form">dijit view helper
                documentation</link>, ComboBoxes are a hybrid between select
            and text input, allowing for autocompletion and the ability to
            specify an alternate to the options provided. FilteringSelects are
            the same, but do not allow arbitrary input.
        </para>

        <note>
            <title>ComboBoxes return the label values</title>

            <para>
                ComboBoxes return the label values, and not the option values,
                which can lead to a disconnect in expectations. For this reason,
                ComboBoxes do not auto-register an <code>InArray</code>
                validator (though FilteringSelects do).
            </para>
        </note>

        <para>
            The ComboBox and FilteringSelect form elements provide accessors and mutators for
            examining and setting the select options as well as specifying a
            dojo.data datastore (if used). They extend from DijitMulti, which
            allows you to specify select options via the
            <methodname>setMultiOptions()</methodname> and <methodname>setMultiOption()</methodname>
            methods. In addition, the following methods are available:
        </para>

        <itemizedlist>
            <listitem><para>
                <methodname>getStoreInfo()</methodname>: get all datastore information
                currently set. Returns an empty array if no data is currently
                set.
            </para></listitem>

            <listitem><para>
                <methodname>setStoreId($identifier)</methodname>: set the store identifier
                variable (usually referred to by the attribute 'jsId' in Dojo).
                This should be a valid javascript variable name.
            </para></listitem>

            <listitem><para>
                <methodname>getStoreId()</methodname>: retrieve the store identifier
                variable name.
            </para></listitem>

            <listitem><para>
                <methodname>setStoreType($dojoType)</methodname>: set the datastore class
                to use; e.g., "dojo.data.ItemFileReadStore".
            </para></listitem>

            <listitem><para>
                <methodname>getStoreType()</methodname>: get the dojo datastore class to
                use.
            </para></listitem>

            <listitem><para>
                <methodname>setStoreParams(array $params)</methodname>: set any parameters
                used to configure the datastore object. As an example,
                dojo.data.ItemFileReadStore datastore would expect a 'url'
                parameter pointing to a location that would return the
                dojo.data object.
            </para></listitem>

            <listitem><para>
                <methodname>getStoreParams()</methodname>: get any datastore parameters
                currently set; if none, an empty array is returned.
            </para></listitem>

            <listitem><para>
                <methodname>setAutocomplete($flag)</methodname>: indicate whether or not
                the selected item will be used when the user leaves the
                element.
            </para></listitem>

            <listitem><para>
                <methodname>getAutocomplete()</methodname>: get the value of the
                autocomplete flag.
            </para></listitem>
        </itemizedlist>

        <para>
            By default, if no dojo.data store is registered with the element,
            this element registers an <code>InArray</code> validator which
            validates against the array keys of registered options. You can
            disable this behavior by either calling
            <methodname>setRegisterInArrayValidator(false)</methodname>, or by passing a
            false value to the <code>registerInArrayValidator</code>
            configuration key.
        </para>

        <example id="zend.dojo.form.elements.comboBox.selectExample">
            <title>ComboBox dijit element usage as select input</title>

            <programlisting language="php"><![CDATA[
$form->addElement(
    'ComboBox',
    'foo',
    array(
        'label'        => 'ComboBox (select)',
        'value'        => 'blue',
        'autocomplete' => false,
        'multiOptions' => array(
            'red'    => 'Rouge',
            'blue'   => 'Bleu',
            'white'  => 'Blanc',
            'orange' => 'Orange',
            'black'  => 'Noir',
            'green'  => 'Vert',
        ),
    )
);
]]></programlisting>
        </example>

        <example id="zend.dojo.form.elements.comboBox.datastoreExample">
            <title>ComboBox dijit element usage with datastore</title>

            <programlisting language="php"><![CDATA[
$form->addElement(
    'ComboBox',
    'foo',
    array(
        'label'       => 'ComboBox (datastore)',
        'storeId'     => 'stateStore',
        'storeType'   => 'dojo.data.ItemFileReadStore',
        'storeParams' => array(
            'url' => '/js/states.txt',
        ),
        'dijitParams' => array(
            'searchAttr' => 'name',
        ),
    )
);
]]></programlisting>
        </example>

        <para>
            The above examples could also utilize <code>FilteringSelect</code>
            instead of <code>ComboBox</code>.
        </para>
    </sect3>

    <sect3 id="zend.dojo.form.elements.currencyTextBox">
        <title>CurrencyTextBox</title>

        <para>
            The CurrencyTextBox is primarily for supporting currency input. The
            currency may be localized, and can support both fractional and
            non-fractional values.
        </para>

        <para>
            Internally, CurrencyTextBox derives from <link
                linkend="zend.dojo.form.elements.numberTextBox">NumberTextBox</link>,
            <link
                linkend="zend.dojo.form.elements.validationTextBox">ValidationTextBox</link>,
            and <link linkend="zend.dojo.form.elements.textBox">TextBox</link>;
            all methods available to those classes are available. In addition,
            the following constraint methods can be used:
        </para>

        <itemizedlist>
            <listitem><para>
                <methodname>setCurrency($currency)</methodname>: set the currency type to
                use; should follow the <ulink
                    url="http://en.wikipedia.org/wiki/ISO_4217">ISO-4217</ulink>
                specification.
            </para></listitem>

            <listitem><para>
                <methodname>getCurrency()</methodname>: retrieve the current currency type.
            </para></listitem>

            <listitem><para>
                <methodname>setSymbol($symbol)</methodname>: set the 3-letter <ulink
                    url="http://en.wikipedia.org/wiki/ISO_4217">ISO-4217</ulink>
                currency symbol to use.
            </para></listitem>

            <listitem><para>
                <methodname>getSymbol()</methodname>: get the current currency symbol.
            </para></listitem>

            <listitem><para>
                <methodname>setFractional($flag)</methodname>: set whether or not the
                currency should allow for fractional values.
            </para></listitem>

            <listitem><para>
                <methodname>getFractional()</methodname>: retrieve the status of the
                fractional flag.
            </para></listitem>
        </itemizedlist>

        <example id="zend.dojo.form.elements.currencyTextBox.example">
            <title>Example CurrencyTextBox dijit element usage</title>

            <programlisting language="php"><![CDATA[
$form->addElement(
    'CurrencyTextBox',
    'foo',
    array(
        'label'          => 'Currency:',
        'required'       => true,
        'currency'       => 'USD',
        'invalidMessage' => 'Invalid amount. ' .
                            'Include dollar sign, commas, and cents.',
        'fractional'     => false,
    )
);
]]></programlisting>
        </example>
    </sect3>

    <sect3 id="zend.dojo.form.elements.dateTextBox">
        <title>DateTextBox</title>

        <para>
            DateTextBox provides a calendar drop-down for selecting a date, as
            well as client-side date validation and formatting.
        </para>

        <para>
            Internally, DateTextBox derives from <link
                linkend="zend.dojo.form.elements.validationTextBox">ValidationTextBox</link>
            and <link linkend="zend.dojo.form.elements.textBox">TextBox</link>;
            all methods available to those classes are available. In addition,
            the following methods can be used to set individual constraints:
        </para>

        <itemizedlist>
            <listitem><para>
                <methodname>setAmPm($flag)</methodname> and <methodname>getAmPm()</methodname>:
                Whether or not to use AM/PM strings in times.
            </para></listitem>

            <listitem><para>
                <methodname>setStrict($flag)</methodname> and <methodname>getStrict()</methodname>:
                whether or not to use strict regular expression matching when
                validating input. If false, which is the default, it will be
                lenient about whitespace and some abbreviations.
            </para></listitem>

            <listitem><para>
                <methodname>setLocale($locale)</methodname> and
                <methodname>getLocale()</methodname>: Set and retrieve the locale to use with this
                specific element.
            </para></listitem>

            <listitem><para>
                <methodname>setDatePattern($pattern)</methodname> and
                <methodname>getDatePattern()</methodname>: provide and retrieve the <ulink
                    url="http://www.unicode.org/reports/tr35/#Date_Format_Patterns">unicode
                    date format pattern</ulink> for formatting the date.
            </para></listitem>

            <listitem><para>
                <methodname>setFormatLength($formatLength)</methodname> and
                <methodname>getFormatLength()</methodname>: provide and retrieve the format
                length type to use; should be one of "long", "short", "medium"
                or "full".
            </para></listitem>

            <listitem><para>
                <methodname>setSelector($selector)</methodname> and
                <methodname>getSelector()</methodname>: provide and retrieve the style of
                selector; should be either "date" or "time".
            </para></listitem>
        </itemizedlist>

        <example id="zend.dojo.form.elements.dateTextBox.example">
            <title>Example DateTextBox dijit element usage</title>

            <programlisting language="php"><![CDATA[
$form->addElement(
    'DateTextBox',
    'foo',
    array(
        'label'          => 'Date:',
        'required'       => true,
        'invalidMessage' => 'Invalid date specified.',
        'formatLength'   => 'long',
    )
);
]]></programlisting>
        </example>
    </sect3>

    <sect3 id="zend.dojo.form.elements.editor">
        <title>Editor</title>

        <para>
            Editor provides a WYSIWYG editor that can be used to both create and
            edit rich HTML content. dijit.Editor is pluggable and may be
            extended with custom plugins if desired; 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>

        <para>
            The Editor form element provides a number of accessors and mutators
            for manipulating various dijit parameters, as follows:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis>captureEvents</emphasis> are events that connect
                    to the editing area itself. The following accessors and
                    mutators are available for manipulating capture events:
                </para>

                <itemizedlist>
                    <listitem>
                        <para><methodname>addCaptureEvent($event)</methodname></para>
                    </listitem>
                    <listitem>
                        <para><methodname>addCaptureEvents(array $events)</methodname></para>
                    </listitem>
                    <listitem>
                        <para><methodname>setCaptureEvents(array $events)</methodname></para>
                    </listitem>
                    <listitem><para><methodname>getCaptureEvents()</methodname></para></listitem>
                    <listitem>
                        <para><methodname>hasCaptureEvent($event)</methodname></para>
                    </listitem>
                    <listitem>
                        <para><methodname>removeCaptureEvent($event)</methodname></para>
                    </listitem>
                    <listitem>
                        <para><methodname>clearCaptureEvents()</methodname></para>
                    </listitem>
                </itemizedlist>
            </listitem>

            <listitem>
                <para>
                    <emphasis>events</emphasis> are standard DOM events, such as
                    onClick, onKeyUp, etc. The following accessors and mutators
                    are available for manipulating events:
                </para>

                <itemizedlist>
                    <listitem><para><methodname>addEvent($event)</methodname></para></listitem>
                    <listitem>
                        <para><methodname>addEvents(array $events)</methodname></para>
                    </listitem>
                    <listitem>
                        <para><methodname>setEvents(array $events)</methodname></para>
                    </listitem>
                    <listitem><para><methodname>getEvents()</methodname></para></listitem>
                    <listitem><para><methodname>hasEvent($event)</methodname></para></listitem>
                    <listitem><para><methodname>removeEvent($event)</methodname></para></listitem>
                    <listitem><para><methodname>clearEvents()</methodname></para></listitem>
                </itemizedlist>
            </listitem>

            <listitem>
                <para>
                    <emphasis>plugins</emphasis> add functionality to the
                    Editor -- additional tools for the toolbar, additional
                    styles to allow, etc. The following accessors and mutators
                    are available for manipulating plugins:
                </para>

                <itemizedlist>
                    <listitem><para><methodname>addPlugin($plugin)</methodname></para></listitem>
                    <listitem>
                        <para><methodname>addPlugins(array $plugins)</methodname></para>
                    </listitem>
                    <listitem>
                        <para><methodname>setPlugins(array $plugins)</methodname></para>
                    </listitem>
                    <listitem><para><methodname>getPlugins()</methodname></para></listitem>
                    <listitem><para><methodname>hasPlugin($plugin)</methodname></para></listitem>
                    <listitem><para><methodname>removePlugin($plugin)</methodname></para></listitem>
                    <listitem><para><methodname>clearPlugins()</methodname></para></listitem>
                </itemizedlist>
            </listitem>

            <listitem>
                <para>
                    <emphasis>editActionInterval</emphasis> is used to group
                    events for undo operations. By default, this value is 3
                    seconds. The method
                    <methodname>setEditActionInterval($interval)</methodname> may be used to
                    set the value, while <methodname>getEditActionInterval()</methodname>
                    will retrieve it.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>focusOnLoad</emphasis> is used to determine
                    whether this particular editor will receive focus when the
                    page has loaded. By default, this is false. The method
                    <methodname>setFocusOnLoad($flag)</methodname> may be used to
                    set the value, while <methodname>getFocusOnLoad()</methodname>
                    will retrieve it.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>height</emphasis> specifies the height of the
                    editor; by default, this is 300px. The method
                    <methodname>setHeight($height)</methodname> may be used to set the
                    value, while <methodname>getHeight()</methodname> will retrieve it.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>inheritWidth</emphasis> is used to determine
                    whether the editor will use the parent container's width or
                    simply default to 100% width. By default, this is false
                    (i.e., it will fill the width of the window). The method
                    <methodname>setInheritWidth($flag)</methodname> may be used to set the
                    value, while <methodname>getInheritWidth()</methodname> will retrieve
                    it.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>minHeight</emphasis> indicates the minimum height
                    of the editor; by default, this is 1em. The method
                    <methodname>setMinHeight($height)</methodname> may be used to set the
                    value, while <methodname>getMinHeight()</methodname> will retrieve it.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>styleSheets</emphasis> indicate what additional
                    <acronym>CSS</acronym> stylesheets should be used to affect the display of the
                    Editor. By default, none are registered, and it inherits the
                    page styles. The following accessors and mutators are
                    available for manipulating editor stylesheets:
                </para>

                <itemizedlist>
                    <listitem>
                        <para><methodname>addStyleSheet($styleSheet)</methodname></para>
                    </listitem>
                    <listitem>
                        <para><methodname>addStyleSheets(array $styleSheets)</methodname></para>
                    </listitem>
                    <listitem>
                        <para><methodname>setStyleSheets(array $styleSheets)</methodname></para>
                    </listitem>
                    <listitem><para><methodname>getStyleSheets()</methodname></para></listitem>
                    <listitem>
                        <para><methodname>hasStyleSheet($styleSheet)</methodname></para>
                    </listitem>
                    <listitem>
                        <para><methodname>removeStyleSheet($styleSheet)</methodname></para>
                    </listitem>
                    <listitem><para><methodname>clearStyleSheets()</methodname></para></listitem>
                </itemizedlist>
            </listitem>
        </itemizedlist>

        <example id="zend.dojo.form.elements.editor.example">
            <title>Example Editor dijit element usage</title>

            <programlisting language="php"><![CDATA[
$form->addElement('editor', 'content', array(
    'plugins'            => array('undo', '|', 'bold', 'italic'),
    'editActionInterval' => 2,
    'focusOnLoad'        => true,
    'height'             => '250px',
    'inheritWidth'       => true,
    'styleSheets'        => array('/js/custom/editor.css'),
));
]]></programlisting>
        </example>
    </sect3>

    <sect3 id="zend.dojo.form.elements.horizontalSlider">
        <title>HorizontalSlider</title>

        <para>
            HorizontalSlider provides a slider UI widget for selecting a
            numeric value in a range. Internally, it sets the value of a hidden
            element which is submitted by the form.
        </para>

        <para>
            HorizontalSlider derives from the <link
                linkend="zend.dojo.form.elements.slider">abstract Slider dijit
                element</link>. Additionally, it has a variety of methods for
            setting and configuring slider rules and rule labels.
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>setTopDecorationDijit($dijit)</methodname> and
                    <methodname>setBottomDecorationDijit($dijit)</methodname>: set the name
                    of the dijit to use for either the top or bottom of the
                    slider. This should not include the "dijit.form." prefix,
                    but rather only the final name -- one of "HorizontalRule"
                    or "HorizontalRuleLabels".
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>setTopDecorationContainer($container)</methodname> and
                    <methodname>setBottomDecorationContainer($container)</methodname>:
                    specify the name to use for the container element of the
                    rules; e.g. 'topRule', 'topContainer', etc.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>setTopDecorationLabels(array $labels)</methodname> and
                    <methodname>setBottomDecorationLabels(array $labels)</methodname>: set
                    the labels to use for one of the RuleLabels dijit types.
                    These should be an indexed array; specify a single empty
                    space to skip a given label position (such as the beginning
                    or end).
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>setTopDecorationParams(array $params)</methodname> and
                    <methodname>setBottomDecorationParams(array $params)</methodname>:
                    dijit parameters to use when configuring the given Rule or
                    RuleLabels dijit.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>setTopDecorationAttribs(array $attribs)</methodname> and
                    <methodname>setBottomDecorationAttribs(array $attribs)</methodname>:
                    HTML attributes to specify for the given Rule or RuleLabels
                    HTML element container.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getTopDecoration()</methodname> and
                    <methodname>getBottomDecoration()</methodname>: retrieve all metadata
                    for a given Rule or RuleLabels definition, as provided by
                    the above mutators.
                </para>
            </listitem>
        </itemizedlist>

        <example id="zend.dojo.form.elements.horizontalSlider.example">
            <title>Example HorizontalSlider dijit element usage</title>

            <para>
                The following will create a horizontal slider selection with
                integer values ranging from -10 to 10. The top will have labels
                at the 20%, 40%, 60%, and 80% marks. The bottom will have rules
                at 0, 50%, and 100%. Each time the value is changed, the hidden
                element storing the value will be updated.
            </para>

            <programlisting language="php"><![CDATA[
$form->addElement(
    'HorizontalSlider',
    'horizontal',
    array(
        'label'                     => 'HorizontalSlider',
        'value'                     => 5,
        'minimum'                   => -10,
        'maximum'                   => 10,
        'discreteValues'            => 11,
        'intermediateChanges'       => true,
        'showButtons'               => true,
        'topDecorationDijit'        => 'HorizontalRuleLabels',
        'topDecorationContainer'    => 'topContainer',
        'topDecorationLabels'       => array(
                ' ',
                '20%',
                '40%',
                '60%',
                '80%',
                ' ',
        ),
        'topDecorationParams'      => array(
            'container' => array(
                'style' => 'height:1.2em; font-size=75%;color:gray;',
            ),
            'list' => array(
                'style' => 'height:1em; font-size=75%;color:gray;',
            ),
        ),
        'bottomDecorationDijit'     => 'HorizontalRule',
        'bottomDecorationContainer' => 'bottomContainer',
        'bottomDecorationLabels'    => array(
                '0%',
                '50%',
                '100%',
        ),
        'bottomDecorationParams'   => array(
            'list' => array(
                'style' => 'height:1em; font-size=75%;color:gray;',
            ),
        ),
    )
);
]]></programlisting>
        </example>
    </sect3>

    <sect3 id="zend.dojo.form.elements.numberSpinner">
        <title>NumberSpinner</title>

        <para>
            A number spinner is a text element for entering numeric values; it
            also includes elements for incrementing and decrementing the value
            by a set amount.
        </para>

        <para>
            The following methods are available:
        </para>

        <itemizedlist>
            <listitem><para>
                <methodname>setDefaultTimeout($timeout)</methodname> and
                <methodname>getDefaultTimeout()</methodname>: set and retrieve the default
                timeout, in milliseconds, between when the button is held
                pressed and the value is changed.
            </para></listitem>

            <listitem><para>
                <methodname>setTimeoutChangeRate($rate)</methodname> and
                <methodname>getTimeoutChangeRate()</methodname>: set and retrieve the
                rate, in milliseconds, at which changes will be made when a
                button is held pressed.
            </para></listitem>

            <listitem><para>
                <methodname>setLargeDelta($delta)</methodname> and
                <methodname>getLargeDelta()</methodname>: set and retrieve the amount by
                which the numeric value should change when a button is held
                pressed.
            </para></listitem>

            <listitem><para>
                <methodname>setSmallDelta($delta)</methodname> and
                <methodname>getSmallDelta()</methodname>: set and retrieve the delta by
                which the number should change when a button is pressed once.
            </para></listitem>

            <listitem><para>
                <methodname>setIntermediateChanges($flag)</methodname> and
                <methodname>getIntermediateChanges()</methodname>: set and retrieve the
                flag indicating whether or not each value change should be
                shown when a button is held pressed.
            </para></listitem>

            <listitem><para>
                <methodname>setRangeMessage($message)</methodname> and
                <methodname>getRangeMessage()</methodname>: set and retrieve the message
                indicating the range of values available.
            </para></listitem>

            <listitem><para>
                <methodname>setMin($value)</methodname> and <methodname>getMin()</methodname>: set
                and retrieve the minimum value possible.
            </para></listitem>

            <listitem><para>
                <methodname>setMax($value)</methodname> and <methodname>getMax()</methodname>: set
                and retrieve the maximum value possible.
            </para></listitem>
        </itemizedlist>

        <example id="zend.dojo.form.elements.numberSpinner.example">
            <title>Example NumberSpinner dijit element usage</title>

            <programlisting language="php"><![CDATA[
$form->addElement(
    'NumberSpinner',
    'foo',
    array(
        'value'             => '7',
        'label'             => 'NumberSpinner',
        'smallDelta'        => 5,
        'largeDelta'        => 25,
        'defaultTimeout'    => 500,
        'timeoutChangeRate' => 100,
        'min'               => 9,
        'max'               => 1550,
        'places'            => 0,
        'maxlength'         => 20,
    )
);
]]></programlisting>
        </example>
    </sect3>

    <sect3 id="zend.dojo.form.elements.numberTextBox">
        <title>NumberTextBox</title>

        <para>
            A number text box is a text element for entering numeric values;
            unlike NumberSpinner, numbers are entered manually. Validations and
            constraints can be provided to ensure the number stays in a
            particular range or format.
        </para>

        <para>
            Internally, NumberTextBox derives from <link
                linkend="zend.dojo.form.elements.validationTextBox">ValidationTextBox</link>
            and <link linkend="zend.dojo.form.elements.textBox">TextBox</link>;
            all methods available to those classes are available. In addition,
            the following methods can be used to set individual constraints:
        </para>

        <itemizedlist>
            <listitem><para>
                <methodname>setLocale($locale)</methodname> and
                <methodname>getLocale()</methodname>: specify and retrieve a specific or alternate
                locale to use with this dijit.
            </para></listitem>

            <listitem><para>
                <methodname>setPattern($pattern)</methodname> and
                <methodname>getPattern()</methodname>: set and retrieve a <ulink
                    url="http://www.unicode.org/reports/tr35/#Number_Format_Patterns">number
                    pattern format</ulink> to use to format the number.
            </para></listitem>

            <listitem><para>
                <methodname>setType($type)</methodname> and <methodname>getType()</methodname>: set
                and retrieve the numeric format type to use (should be one of
                'decimal', 'percent', or 'currency').
            </para></listitem>

            <listitem><para>
                <methodname>setPlaces($places)</methodname> and
                <methodname>getPlaces()</methodname>: set and retrieve the number of decimal places
                to support.
            </para></listitem>

            <listitem><para>
                <methodname>setStrict($flag)</methodname> and <methodname>getStrict()</methodname>:
                set and retrieve the value of the strict flag, which indicates how
                much leniency is allowed in relation to whitespace and
                non-numeric characters.
            </para></listitem>
        </itemizedlist>

        <example id="zend.dojo.form.elements.numberTextBox.example">
            <title>Example NumberTextBox dijit element usage</title>

            <programlisting language="php"><![CDATA[
$form->addElement(
    'NumberTextBox',
    'elevation',
    array(
        'label'          => 'NumberTextBox',
        'required'       => true,
        'invalidMessage' => 'Invalid elevation.',
        'places'         => 0,
        'constraints'    => array(
            'min'    => -20000,
            'max'    => 20000,
        ),
    )
);
]]></programlisting>
        </example>
    </sect3>

    <sect3 id="zend.dojo.form.elements.passwordTextBox">
        <title>PasswordTextBox</title>

        <para>
            PasswordTextBox is simply a ValidationTextBox that is tied to a
            password input; its sole purpose is to allow for a dijit-themed text
            entry for passwords that also provides client-side validation.
        </para>

        <para>
            Internally, PasswordTextBox derives from <link
                linkend="zend.dojo.form.elements.validationTextBox">ValidationTextBox</link>
            and <link linkend="zend.dojo.form.elements.textBox">TextBox</link>;
            all methods available to those classes are available.
        </para>

        <example id="zend.dojo.form.elements.passwordTextBox.example">
            <title>Example PasswordTextBox dijit element usage</title>

            <programlisting language="php"><![CDATA[
$form->addElement(
    'PasswordTextBox',
    'password',
    array(
        'label'          => 'Password',
        'required'       => true,
        'trim'           => true,
        'lowercase'      => true,
        'regExp'         => '^[a-z0-9]{6,}$',
        'invalidMessage' => 'Invalid password; ' .
                            'must be at least 6 alphanumeric characters',
    )
);
]]></programlisting>
        </example>
    </sect3>

    <sect3 id="zend.dojo.form.elements.radioButton">
        <title>RadioButton</title>

        <para>
            RadioButton wraps standard radio input elements to provide a
            consistent look and feel with other dojo dijits.
        </para>

        <para>
            RadioButton extends from DijitMulti, which
            allows you to specify select options via the
            <methodname>setMultiOptions()</methodname> and <methodname>setMultiOption()</methodname>
            methods.
        </para>

        <para>
            By default, this element registers an <code>InArray</code> validator
            which validates against the array keys of registered options. You
            can disable this behavior by either calling
            <methodname>setRegisterInArrayValidator(false)</methodname>, or by passing a
            false value to the <code>registerInArrayValidator</code>
            configuration key.
        </para>

        <example id="zend.dojo.form.elements.radioButton.example">
            <title>Example RadioButton dijit element usage</title>

            <programlisting language="php"><![CDATA[
$form->addElement(
    'RadioButton',
    'foo',
    array(
        'label' => 'RadioButton',
        'multiOptions'  => array(
            'foo' => 'Foo',
            'bar' => 'Bar',
            'baz' => 'Baz',
        ),
        'value' => 'bar',
    )
);
]]></programlisting>
        </example>
    </sect3>

    <sect3 id="zend.dojo.form.elements.simpletextarea">
        <title>SimpleTextarea</title>

        <para>
            SimpleTextarea acts primarily like a standard HTML textarea. However, it
            does not support either the rows or cols settings. Instead, the
            textarea width should be specified using standard <acronym>CSS</acronym> measurements.
            Unlike Textarea, it will not grow automatically
        </para>

        <example id="zend.dojo.form.elements.simpletextarea.example">
            <title>Example SimpleTextarea dijit element usage</title>

            <programlisting language="php"><![CDATA[
$form->addElement(
    'SimpleTextarea',
    'simpletextarea',
    array(
        'label'    => 'SimpleTextarea',
        'required' => true,
        'style'    => 'width: 80em; height: 25em;',
    )
);
]]></programlisting>
        </example>
    </sect3>

    <sect3 id="zend.dojo.form.elements.slider">
        <title>Slider abstract element</title>

        <para>
            Slider is an abstract element from which
            <link linkend="zend.dojo.form.elements.horizontalSlider">HorizontalSlider</link>
            and
            <link linkend="zend.dojo.form.elements.verticalSlider">VerticalSlider</link>
            both derive. It exposes a number of common methods for configuring
            your sliders, including:
        </para>

        <itemizedlist>
            <listitem><para>
                <methodname>setClickSelect($flag)</methodname> and
                <methodname>getClickSelect()</methodname>: set and retrieve the flag
                indicating whether or not clicking the slider changes the
                value.
            </para></listitem>

            <listitem><para>
                <methodname>setIntermediateChanges($flag)</methodname> and
                <methodname>getIntermediateChanges()</methodname>: set and retrieve the
                flag indicating whether or not the dijit will send a
                notification on each slider change event.
            </para></listitem>

            <listitem><para>
                <methodname>setShowButtons($flag)</methodname> and
                <methodname>getShowButtons()</methodname>: set and retrieve the flag
                indicating whether or not buttons on either end will be
                displayed; if so, the user can click on these to change the
                value of the slider.
            </para></listitem>

            <listitem><para>
                <methodname>setDiscreteValues($value)</methodname> and
                <methodname>getDiscreteValues()</methodname>: set and retrieve the number
                of discrete values represented by the slider.
            </para></listitem>

            <listitem><para>
                <methodname>setMaximum($value)</methodname> and
                <methodname>getMaximum()</methodname>: set the maximum value of the slider.
            </para></listitem>

            <listitem><para>
                <methodname>setMinimum($value)</methodname> and
                <methodname>getMinimum()</methodname>: set the minimum value of the slider.
            </para></listitem>

            <listitem><para>
                <methodname>setPageIncrement($value)</methodname> and
                <methodname>getPageIncrement()</methodname>: set the amount by which the
                slider will change on keyboard events.
            </para></listitem>
        </itemizedlist>

        <para>
            Example usage is provided with each concrete extending class.
        </para>
    </sect3>

    <sect3 id="zend.dojo.form.elements.submitButton">
        <title>SubmitButton</title>

        <para>
            While there is no Dijit named SubmitButton, we include one here to
            provide a button dijit capable of submitting a form without
            requiring any additional javascript bindings. It works exactly like
            the <link linkend="zend.dojo.form.elements.button">Button
                dijit</link>.
        </para>

        <example id="zend.dojo.form.elements.submitButton.example">
            <title>Example SubmitButton dijit element usage</title>

            <programlisting language="php"><![CDATA[
$form->addElement(
    'SubmitButton',
    'foo',
    array(
        'required'   => false,
        'ignore'     => true,
        'label'      => 'Submit Button!',
    )
);
]]></programlisting>
        </example>
    </sect3>

    <sect3 id="zend.dojo.form.elements.textBox">
        <title>TextBox</title>

        <para>
            TextBox is included primarily to provide a text input with
            consistent look-and-feel to the other dijits. However, it also
            includes some minor filtering and validation capabilities,
            represented in the following methods:
        </para>

        <itemizedlist>
            <listitem><para>
                <methodname>setLowercase($flag)</methodname> and
                <methodname>getLowercase()</methodname>: set and retrieve the flag
                indicating whether or not input should be cast to lowercase.
            </para></listitem>

            <listitem><para>
                <methodname>setPropercase($flag)</methodname> and
                <methodname>getPropercase()</methodname>: set and retrieve the flag
                indicating whether or not the input should be cast to Proper
                Case.
            </para></listitem>

            <listitem><para>
                <methodname>setUppercase($flag)</methodname> and
                <methodname>getUppercase()</methodname>: set and retrieve
                the flag indicating whether or not the input should be cast to UPPERCASE.
            </para></listitem>

            <listitem><para>
                <methodname>setTrim($flag)</methodname> and <methodname>getTrim()</methodname>: set
                and retrieve the flag indicating whether or not leading or trailing
                whitespace should be stripped.
            </para></listitem>

            <listitem><para>
                <methodname>setMaxLength($length)</methodname> and
                <methodname>getMaxLength()</methodname>: set and retrieve the maximum
                length of input.
            </para></listitem>
        </itemizedlist>

        <example id="zend.dojo.form.elements.textBox.example">
            <title>Example TextBox dijit element usage</title>

            <programlisting language="php"><![CDATA[
$form->addElement(
    'TextBox',
    'foo',
    array(
        'value'      => 'some text',
        'label'      => 'TextBox',
        'trim'       => true,
        'propercase' => true,
    )
);
]]></programlisting>
        </example>
    </sect3>

    <sect3 id="zend.dojo.form.elements.textarea">
        <title>Textarea</title>

        <para>
            Textarea acts primarily like a standard HTML textarea. However, it
            does not support either the rows or cols settings. Instead, the
            textarea width should be specified using standard <acronym>CSS</acronym> measurements;
            rows should be omitted entirely. The textarea will then grow
            vertically as text is added to it.
        </para>

        <example id="zend.dojo.form.elements.textarea.example">
            <title>Example Textarea dijit element usage</title>

            <programlisting language="php"><![CDATA[
$form->addElement(
    'Textarea',
    'textarea',
    array(
        'label'    => 'Textarea',
        'required' => true,
        'style'    => 'width: 200px;',
    )
);
]]></programlisting>
        </example>
    </sect3>

    <sect3 id="zend.dojo.form.elements.timeTextBox">
        <title>TimeTextBox</title>

        <para>
            TimeTextBox is a text input that provides a drop-down for selecting
            a time. The drop-down may be configured to show a certain window of
            time, with specified increments.
        </para>

        <para>
            Internally, TimeTextBox derives from <link
                linkend="zend.dojo.form.elements.dateTextBox">DateTextBox</link>,
            <link
                linkend="zend.dojo.form.elements.validationTextBox">ValidationTextBox</link>
            and <link linkend="zend.dojo.form.elements.textBox">TextBox</link>;
            all methods available to those classes are available. In addition,
            the following methods can be used to set individual constraints:
        </para>

        <itemizedlist>
            <listitem><para>
                <methodname>setTimePattern($pattern)</methodname> and
                <methodname>getTimePattern()</methodname>: set and retrieve the <ulink
                    url="http://www.unicode.org/reports/tr35/#Date_Format_Patterns">unicode
                    time format pattern</ulink> for formatting the time.
            </para></listitem>

            <listitem><para>
                <methodname>setClickableIncrement($format)</methodname> and
                <methodname>getClickableIncrement()</methodname>: set the <ulink
                    url="http://en.wikipedia.org/wiki/ISO_8601">ISO-8601</ulink>
                string representing the amount by which every clickable element
                in the time picker increases.
            </para></listitem>

            <listitem><para>
                <methodname>setVisibleIncrement($format)</methodname> and
                <methodname>getVisibleIncrement()</methodname>: set the increment visible
                in the time chooser; must follow ISO-8601 formats.
            </para></listitem>

            <listitem><para>
                <methodname>setVisibleRange($format)</methodname> and
                <methodname>getVisibleRange()</methodname>: set and retrieve the range of
                time visible in the time chooser at any given moment; must
                follow ISO-8601 formats.
            </para></listitem>
        </itemizedlist>

        <example id="zend.dojo.form.elements.timeTextBox.example">
            <title>Example TimeTextBox dijit element usage</title>

            <para>
                The following will create a TimeTextBox that displays 2 hours
                at a time, with increments of 10 minutes.
            </para>

            <programlisting language="php"><![CDATA[
$form->addElement(
    'TimeTextBox',
    'foo',
    array(
        'label'              => 'TimeTextBox',
        'required'           => true,
        'visibleRange'       => 'T04:00:00',
        'visibleIncrement'   => 'T00:10:00',
        'clickableIncrement' => 'T00:10:00',
    )
);
]]></programlisting>
        </example>
    </sect3>

    <sect3 id="zend.dojo.form.elements.validationTextBox">
        <title>ValidationTextBox</title>

        <para>
            ValidationTextBox provides the ability to add validations and constraints to a text
            input. Internally, it derives from <link
                linkend="zend.dojo.form.elements.textBox">TextBox</link>, and adds the following
            accessors and mutators for manipulating dijit parameters:
        </para>

        <itemizedlist>
            <listitem><para>
                <methodname>setInvalidMessage($message)</methodname> and
                <methodname>getInvalidMessage()</methodname>: set and retrieve the tooltip
                message to display when the value does not validate.
            </para></listitem>

            <listitem><para>
                <methodname>setPromptMessage($message)</methodname> and
                <methodname>getPromptMessage()</methodname>: set and retrieve the tooltip
                message to display for element usage.
            </para></listitem>

            <listitem><para>
                <methodname>setRegExp($regexp)</methodname> and
                <methodname>getRegExp()</methodname>: set and retrieve the regular expression to
                use for validating the element. The regular expression does not need boundaries
                (unlike <acronym>PHP</acronym>'s preg* family of functions).
            </para></listitem>

            <listitem><para>
                <methodname>setConstraint($key, $value)</methodname> and
                <methodname>getConstraint($key)</methodname>: set and retrieve additional
                constraints to use when validating the element; used primarily
                with subclasses. Constraints are stored in the 'constraints'
                key of the dijit parameters.
            </para></listitem>

            <listitem><para>
                <methodname>setConstraints(array $constraints)</methodname> and
                <methodname>getConstraints()</methodname>: set and retrieve individual
                constraints to use when validating the element; used primarily
                with subclasses.
            </para></listitem>

            <listitem><para>
                <methodname>hasConstraint($key)</methodname>: test whether a given
                constraint exists.
            </para></listitem>

            <listitem><para>
                <methodname>removeConstraint($key)</methodname> and
                <methodname>clearConstraints()</methodname>: remove an individual or all
                constraints for the element.
            </para></listitem>
        </itemizedlist>

        <example id="zend.dojo.form.elements.validationTextBox.example">
            <title>Example ValidationTextBox dijit element usage</title>

            <para>
                The following will create a ValidationTextBox that requires a
                single string consisting solely of word characters (i.e., no
                spaces, most punctuation is invalid).
            </para>

            <programlisting language="php"><![CDATA[
$form->addElement(
    'ValidationTextBox',
    'foo',
    array(
        'label'          => 'ValidationTextBox',
        'required'       => true,
        'regExp'         => '[\w]+',
        'invalidMessage' => 'Invalid non-space text.',
    )
);
]]></programlisting>
        </example>
    </sect3>

    <sect3 id="zend.dojo.form.elements.verticalSlider">
        <title>VerticalSlider</title>

        <para>
            VerticalSlider is the sibling of <link
                linkend="zend.dojo.form.elements.horizontalSlider">HorizontalSlider</link>,
            and operates in every way like that element. The only real
            difference is that the 'top*' and 'bottom*' methods are replaced by
            'left*' and 'right*', and instead of using HorizontalRule and
            HorizontalRuleLabels, VerticalRule and VerticalRuleLabels should be
            used.
        </para>

        <example id="zend.dojo.form.elements.verticalSlider.example">
            <title>Example VerticalSlider dijit element usage</title>

            <para>
                The following will create a vertical slider selection with
                integer values ranging from -10 to 10. The left will have labels
                at the 20%, 40%, 60%, and 80% marks. The right will have rules
                at 0, 50%, and 100%. Each time the value is changed, the hidden
                element storing the value will be updated.
            </para>

            <programlisting language="php"><![CDATA[
$form->addElement(
    'VerticalSlider',
    'foo',
    array(
        'label'                    => 'VerticalSlider',
        'value'                    => 5,
        'style'                    => 'height: 200px; width: 3em;',
        'minimum'                  => -10,
        'maximum'                  => 10,
        'discreteValues'           => 11,
        'intermediateChanges'      => true,
        'showButtons'              => true,
        'leftDecorationDijit'      => 'VerticalRuleLabels',
        'leftDecorationContainer'  => 'leftContainer',
        'leftDecorationLabels'     => array(
                ' ',
                '20%',
                '40%',
                '60%',
                '80%',
                ' ',
        ),
        'rightDecorationDijit' => 'VerticalRule',
        'rightDecorationContainer' => 'rightContainer',
        'rightDecorationLabels' => array(
                '0%',
                '50%',
                '100%',
        ),
    )
);
]]></programlisting>
        </example>
    </sect3>
</sect2>
<!--
vim:se ts=4 sw=4 et:
-->