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 <constant>TRUE</constant>, otherwise return
                <constant>FALSE</constant>.
            </para>
        </listitem>

        <listitem>
            <para>
                <methodname>getDijitParam($key)</methodname>: retrieve the given dijit
                parameter. If not available, a <constant>NULL</constant> 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 <property>dijitParams</property> 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 <classname>Multi</classname> 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 <constant>TRUE</constant>. This is useful
                    for determining which button was used when a form was submitted.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Additionally, only the decorators <classname>DijitElement</classname> and
            <classname>DtDdWrapper</classname> 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 <classname>InArray</classname>
                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
            <command>dojo.data</command> 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., "<command>dojo.data.ItemFileReadStore</command>".
                </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,
                    <command>dojo.data.ItemFileReadStore</command> datastore would expect a 'url'
                    parameter pointing to a location that would return the
                    <command>dojo.data</command> 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 <command>dojo.data</command> store is registered with the element,
            this element registers an <classname>InArray</classname> 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
            <constant>FALSE</constant> value to the <property>registerInArrayValidator</property>
            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 <classname>FilteringSelect</classname>
            instead of <classname>ComboBox</classname>.
        </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 or 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 <constant>FALSE</constant>, 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 <acronym>WYSIWYG</acronym> editor that can be used to both create and
            edit rich <acronym>HTML</acronym> content. <command>dijit.Editor</command> is pluggable
            and may be extended with custom plugins if desired; see <ulink
                url="http://dojotoolkit.org/reference-guide/dijit/Editor.html">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 <acronym>DOM</acronym> 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 <constant>FALSE</constant>. 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 <constant>FALSE</constant>
                    (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>

        <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> documentation indicates that
                having it built on an <acronym>HTML</acronym> <acronym>TEXTAREA</acronym> can
                potentially have security implications.
            </para>

            <para>
                That said, there may be times when you want an Editor widget that can gracefully
                degrade to a <acronym>TEXTAREA</acronym>. In such situations, you can do so by
                setting the <property>degrade</property> property to <constant>TRUE</constant>:
            </para>

            <programlisting language="php"><![CDATA[
// At instantiation:
$editor = new Zend_Dojo_Form_Element_Editor('foo', array(
    'degrade' => true,
));

// Construction via the form:
$form->addElement('editor', 'content', array(
    'degrade' => true,
));

// Or after instantiation:
$editor->degrade = true;
]]></programlisting>
        </note>
    </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>:
                    <acronym>HTML</acronym> attributes to specify for the given Rule or RuleLabels
                    <acronym>HTML</acronym> 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 <classname>InArray</classname> 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
            <constant>FALSE</constant> value to the <property>registerInArrayValidator</property>
            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 <acronym>HTML</acronym> 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
                    <acronym>UPPERCASE</acronym>.
                </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 <acronym>HTML</acronym> 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 <constant>ISO_8601</constant> 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 <constant>ISO_8601</constant> 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:
-->