repo_zf1/documentation/manual/en/module_specs/Zend_Form-StandardElements.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.form.standardElements">
    <title>Standard Form Elements Shipped With Zend Framework</title>

    <para>
        Zend Framework ships with concrete element classes covering most <acronym>HTML</acronym>
        form elements. Most simply specify a particular view helper for use when
        decorating the element, but several offer additional functionality. The
        following is a list of all such classes, as well as descriptions of the
        functionality they offer.
    </para>

    <sect2 id="zend.form.standardElements.button">
        <title>Zend_Form_Element_Button</title>

        <para>
            Used for creating <acronym>HTML</acronym> button elements,
            <classname>Zend_Form_Element_Button</classname> extends <link
                linkend="zend.form.standardElements.submit">Zend_Form_Element_Submit</link>,
            specifying some custom functionality. It specifies the 'formButton'
            view helper for decoration.
        </para>

        <para>
            Like the submit element, it uses the element's label as the element
            value for display purposes; in other words, to set the text of the
            button, set the value of the element. The label will be translated
            if a translation adapter is present.
        </para>

        <para>
            Because the label is used as part of the element, the button element
            uses only the <link
                linkend="zend.form.standardDecorators.viewHelper">ViewHelper</link>
            and <link
                linkend="zend.form.standardDecorators.dtDdWrapper">DtDdWrapper</link>
            decorators.
        </para>

        <para>
            After populating or validating a form, you can check if the given
            button was clicked using the <methodname>isChecked()</methodname> method.
        </para>
    </sect2>

    <sect2 id="zend.form.standardElements.captcha">
        <title>Zend_Form_Element_Captcha</title>

        <para>
            CAPTCHAs are used to prevent automated submission of forms by bots
            and other automated processes.
        </para>

        <para>
            The Captcha form element allows you to specify which <link
                linkend="zend.captcha.adapters">Zend_Captcha adapter</link> you
            wish to utilize as a form CAPTCHA. It then sets this adapter as a
            validator to the object, and uses a Captcha decorator for rendering
            (which proxies to the CAPTCHA adapter).
        </para>

        <para>
            Adapters may be any adapters in <classname>Zend_Captcha</classname>, as well
            as any custom adapters you may have defined elsewhere. To allow
            this, you may pass an additional plugin loader type key, 'CAPTCHA'
            or 'captcha', when specifying a plugin loader prefix path:
        </para>

        <programlisting language="php"><![CDATA[
$element->addPrefixPath('My_Captcha', 'My/Captcha/', 'captcha');
]]></programlisting>

        <para>
            Captcha's may then be registered using the <methodname>setCaptcha()</methodname>
            method, which can take either a concrete CAPTCHA instance, or the
            short name of a CAPTCHA adapter:
        </para>

        <programlisting language="php"><![CDATA[
// Concrete instance:
$element->setCaptcha(new Zend_Captcha_Figlet());

// Using shortnames:
$element->setCaptcha('Dumb');
]]></programlisting>

        <para>
            If you wish to load your element via configuration, specify either
            the key 'captcha' with an array containing the key 'captcha', or
            both the keys 'captcha' and 'captchaOptions':
        </para>

        <programlisting language="php"><![CDATA[
// Using single captcha key:
$element = new Zend_Form_Element_Captcha('foo', array(
    'label' => "Please verify you're a human",
    'captcha' => array(
        'captcha' => 'Figlet',
        'wordLen' => 6,
        'timeout' => 300,
    ),
));

// Using both captcha and captchaOptions:
$element = new Zend_Form_Element_Captcha('foo', array(
    'label' => "Please verify you're a human",
    'captcha' => 'Figlet',
    'captchaOptions' => array(
        'captcha' => 'Figlet',
        'wordLen' => 6,
        'timeout' => 300,
    ),
));
]]></programlisting>

        <para>
            The decorator used is determined by querying the captcha adapter. By
            default, the <link
                linkend="zend.form.standardDecorators.captcha">Captcha
                decorator</link> is used, but an adapter may specify a different
            one via its <methodname>getDecorator()</methodname> method.
        </para>

        <para>
            As noted, the captcha adapter itself acts as a validator for the
            element. Additionally, the NotEmpty validator is not used, and the
            element is marked as required. In most cases, you should need to do
            nothing else to have a captcha present in your form.
        </para>
    </sect2>

    <sect2 id="zend.form.standardElements.checkbox">
        <title>Zend_Form_Element_Checkbox</title>

        <para>
            <acronym>HTML</acronym> checkboxes allow you return a specific value, but basically
            operate as booleans. When checked, the checkbox's value is submitted.
            When the checkbox is not checked, nothing is submitted. Internally,
            <classname>Zend_Form_Element_Checkbox</classname> enforces this state.
        </para>

        <para>
            By default, the checked value is '1', and the unchecked value '0'.
            You can specify the values to use using the <methodname>setCheckedValue()</methodname>
            and <methodname>setUncheckedValue()</methodname> accessors, respectively. Internally,
            any time you set the value, if the provided value matches the checked value, then it is
            set, but any other value causes the unchecked value to be set.
        </para>

        <para>
            Additionally, setting the value sets the <property>checked</property>
            property of the checkbox. You can query this using
            <methodname>isChecked()</methodname> or simply accessing the property. Using the
            <methodname>setChecked($flag)</methodname> method will both set the state of the
            flag as well as set the appropriate checked or unchecked value in the
            element. Please use this method when setting the checked state of a
            checkbox element to ensure the value is set properly.
        </para>

        <para>
            <classname>Zend_Form_Element_Checkbox</classname> uses the 'formCheckbox' view
            helper. The checked value is always used to populate it.
        </para>
    </sect2>

    <sect2 id="zend.form.standardElements.file">
        <title>Zend_Form_Element_File</title>

        <para>
            The File form element provides a mechanism for supplying file upload
            fields to your form. It utilizes <link
                linkend="zend.file.transfer.introduction">Zend_File_Transfer</link>
            internally to provide this functionality, and the
            <classname>FormFile</classname> view helper as also the <classname>File</classname>
            decorator to display the form element.
        </para>

        <para>
            By default, it uses the <classname>Http</classname> transfer adapter, which
            introspects the <varname>$_FILES</varname> array and allows you to attach
            validators and filters. Validators and filters attached to the form
            element are in turn attached to the transfer adapter.
        </para>

        <example id="zend.form.standardElements.file.usage">
            <title>File form element usage</title>

            <para>
                The above explanation of using the File form element may seem
                arcane, but actual usage is relatively trivial:
            </para>

            <programlisting language="php"><![CDATA[
$element = new Zend_Form_Element_File('foo');
$element->setLabel('Upload an image:')
        ->setDestination('/var/www/upload');
// ensure only 1 file
$element->addValidator('Count', false, 1);
// limit to 100K
$element->addValidator('Size', false, 102400);
// only JPEG, PNG, and GIFs
$element->addValidator('Extension', false, 'jpg,png,gif');
$form->addElement($element, 'foo');
]]></programlisting>

            <para>
                You also need to ensure that the correct encoding type is provided to
                the form; you should use 'multipart/form-data'. You can do this
                by setting the 'enctype' attribute on the form:
            </para>

            <programlisting language="php"><![CDATA[
$form->setAttrib('enctype', 'multipart/form-data');
]]></programlisting>

            <para>
                After the form is validated successfully, you must receive the file
                to store it in the final destination using <methodname>receive()</methodname>.
                Additionally you can determinate the final location using
                <methodname>getFileName()</methodname>:
            </para>

            <programlisting language="php"><![CDATA[
if (!$form->isValid()) {
    print "Uh oh... validation error";
}

if (!$form->foo->receive()) {
    print "Error receiving the file";
}

$location = $form->foo->getFileName();
]]></programlisting>
        </example>

        <note>
            <title>Default Upload Location</title>

            <para>
                By default, files are uploaded to the system temp directory.
            </para>
        </note>

        <note>
            <title>File values</title>

            <para>
                Within <acronym>HTTP</acronym> a file element has no value. For this reason and
                because of security concerns <methodname>getValue()</methodname> returns only the
                uploaded filename and not the complete path. If you need the file path, call
                <methodname>getFileName()</methodname>, which returns both the path and the name of
                the file.
            </para>
        </note>

        <note>
            <title>Return value of getFileName()</title>

            <para>
                The result returned by the getFileName() method will change depending on how many files the Zend_Form_Element_File uploaded:
            <itemizedlist>
                <listitem>
                    <para>
                        A single file: string containing the single file name.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Multiple files: an array, where each item is a string containing a single file name.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        No files: an empty array
                    </para>
                </listitem>
            </itemizedlist>
            </para>
        </note>

        <para>
            Per default the file will automatically be received when you call
            <methodname>getValues()</methodname> on the form. The reason behind this behaviour is,
            that the file itself is the value of the file element.
        </para>

        <programlisting language="php"><![CDATA[
$form->getValues();
]]></programlisting>

        <note>
            <para>
                Therefor another call of <methodname>receive()</methodname> after calling
                <methodname>getValues()</methodname> will not have an effect. Also creating a
                instance of <classname>Zend_File_Transfer</classname> will not have an effect as
                there no file anymore to receive.
            </para>
        </note>

        <para>
            Still, sometimes you may want to call <methodname>getValues()</methodname> without
            receiving the file. You can archive this by calling
            <methodname>setValueDisabled(true)</methodname>. To get the actual value of this flag
            you can call <methodname>isValueDisabled()</methodname>.
        </para>

        <example id="zend.form.standardElements.file.retrievement">
            <title>Explicit file retrievement</title>

            <para>
                First call <methodname>setValueDisabled(true)</methodname>.
            </para>

            <programlisting language="php"><![CDATA[
$element = new Zend_Form_Element_File('foo');
$element->setLabel('Upload an image:')
        ->setDestination('/var/www/upload')
        ->setValueDisabled(true);
]]></programlisting>

            <para>
                Now the file will not be received when you call
                <methodname>getValues()</methodname>. So you must call
                <methodname>receive()</methodname> on the file element, or an instance of
                <classname>Zend_File_Transfer</classname> yourself.
            </para>

            <programlisting language="php"><![CDATA[
$values = $form->getValues();

if ($form->isValid($form->getPost())) {
    if (!$form->foo->receive()) {
        print "Upload error";
    }
}
]]></programlisting>
        </example>

        <para>
            There are several states of the uploaded file which can be checked
            with the following methods:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>isUploaded()</methodname>: Checks if the file element has
                    been uploaded or not.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>isReceived()</methodname>: Checks if the file element has
                    already been received.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>isFiltered()</methodname>: Checks if the filters have already
                    been applied to the file element or not.
                </para>
            </listitem>
        </itemizedlist>

        <example id="zend.form.standardElements.file.isuploaded">
            <title>Checking if an optional file has been uploaded</title>

            <programlisting language="php"><![CDATA[
$element = new Zend_Form_Element_File('foo');
$element->setLabel('Upload an image:')
        ->setDestination('/var/www/upload')
        ->setRequired(false);
$element->addValidator('Size', false, 102400);
$form->addElement($element, 'foo');

// The foo file element is optional but when it's given go into here
if ($form->foo->isUploaded()) {
    // foo file given... do something
}
]]></programlisting>
        </example>

        <para>
            <classname>Zend_Form_Element_File</classname> also supports multiple files.
            By calling the <methodname>setMultiFile($count)</methodname> method you can set
            the number of file elements you want to create. This keeps you
            from setting the same settings multiple times.
        </para>

        <example id="zend.form.standardElements.file.multiusage">
            <title>Setting multiple files</title>

            <para>
                Creating a multifile element is the same as setting a single element.
                Just call <methodname>setMultiFile()</methodname> after the element is created:
            </para>

            <programlisting language="php"><![CDATA[
$element = new Zend_Form_Element_File('foo');
$element->setLabel('Upload an image:')
        ->setDestination('/var/www/upload');
// ensure minimum 1, maximum 3 files
$element->addValidator('Count', false, array('min' => 1, 'max' => 3));
// limit to 100K
$element->addValidator('Size', false, 102400);
// only JPEG, PNG, and GIFs
$element->addValidator('Extension', false, 'jpg,png,gif');
// defines 3 identical file elements
$element->setMultiFile(3);
$form->addElement($element, 'foo');
]]></programlisting>

            <para>
                You now have 3 identical file upload elements
                with the same settings. To get the set multifile number simply call
                <methodname>getMultiFile()</methodname>.
            </para>

        </example>

        <note>
            <title>File elements in Subforms</title>

            <para>
                When you use file elements in subforms you must set unique names.
                For example, if you name a file element in subform1 "file", you must give
                any file element in subform2 a different name.
            </para>

            <para>
                If there are 2 file elements with the same name, the second
                element is not be displayed or submitted.
            </para>

            <para>
                Additionally, file elements are not rendered within the sub-form. So when
                you add a file element into a subform, then the element will be rendered
                within the main form.
            </para>
        </note>

        <para>
            To limit the size of the file uploaded, you can
            specify the maximum file size by setting the <constant>MAX_FILE_SIZE</constant>
            option on the form. When you set this value by using the
            <methodname>setMaxFileSize($size)</methodname> method, it will be rendered with the
            file element.
        </para>

        <programlisting language="php"><![CDATA[
$element = new Zend_Form_Element_File('foo');
$element->setLabel('Upload an image:')
        ->setDestination('/var/www/upload')
        ->addValidator('Size', false, 102400) // limit to 100K
        ->setMaxFileSize(102400); // limits the filesize on the client side
$form->addElement($element, 'foo');
]]></programlisting>

        <note>
            <title>MaxFileSize with Multiple File Elements</title>

            <para>
                When you use multiple file elements in your form you should set
                the <constant>MAX_FILE_SIZE</constant> only once. Setting it again will
                overwrite the previous value.
            </para>

            <para>
                Note, that this is also the case when you use multiple forms.
            </para>
        </note>
    </sect2>

    <sect2 id="zend.form.standardElements.hidden">
        <title>Zend_Form_Element_Hidden</title>

        <para>
            Hidden elements inject data that should be submitted, but that should not manipulated by
            the user . <classname>Zend_Form_Element_Hidden</classname> accomplishes this with the
            'formHidden' view helper.
        </para>
    </sect2>

    <sect2 id="zend.form.standardElements.hash">
        <title>Zend_Form_Element_Hash</title>

        <para>
            This element provides protection from CSRF attacks on forms,
            ensuring the data is submitted by the user session that generated
            the form and not by a rogue script. Protection is achieved by adding
            a hash element to a form and verifying it when the form is
            submitted.
        </para>

        <para>
            The name of the hash element should be unique. We recommend using
            the <literal>salt</literal> option for the element- two hashes with
            same names and different salts would not collide:
        </para>

        <programlisting language="php"><![CDATA[
$form->addElement('hash', 'no_csrf_foo', array('salt' => 'unique'));
]]></programlisting>

        <para>
            You can set the salt later using the <methodname>setSalt($salt)</methodname>
            method.
        </para>

        <para>
            Internally, the element stores a unique identifier using
            <classname>Zend_Session_Namespace</classname>, and checks for it at
            submission (checking that the TTL has not expired). The 'Identical'
            validator is then used to ensure the submitted hash matches the
            stored hash.
        </para>

        <para>
            The 'formHidden' view helper is used to render the element in the
            form.
        </para>

        <note>
            <title>Testing forms containing Zend_Form_Element_Hash</title>
            <para>
                When unit testing a form containing a <classname>Zend_Form_Element_Hash</classname> 
                it is necessary to call <methodname>initCsrfToken</methodname> and 
                <methodname>initCsrfValidator</methodname> before attempting to
                validate the form.  The hash value of the <classname>Zend_Form_Element_Hash</classname> 
                element must also be injected into the array of values passed as the
                argument to <methodname>Zend_Form::isValid</methodname>
            </para>
            <example id="zend.form.standardElements.hash.unittesting">
                <title>Simple example of testing a CSRF-protected form</title>
                <programlisting language="php"><![CDATA[
public function testCsrfProtectedForm() 
{
    $form = new Zend_Form();
    $form->addElement(new Zend_Form_Element_Hash('csrf'));

    $csrf = $form->getElement('csrf');
    $csrf->initCsrfToken();
    $csrf->initCsrfValidator();

    $this->assertTrue($form->isValid(array(
        'csrf' => $csrf->getHash()
    )));
}]]></programlisting>

            </example>
        </note>
        
    </sect2>

    <sect2 id="zend.form.standardElements.Image">
        <title>Zend_Form_Element_Image</title>

        <para>
            Images can be used as form elements, and you can use these images as
            graphical elements on form buttons.
        </para>

        <para>
            Images need an image source. <classname>Zend_Form_Element_Image</classname>
            allows you to specify this by using the <methodname>setImage()</methodname>
            accessor (or 'image' configuration key). You can also optionally specify a value to use
            when submitting the image using the <methodname>setImageValue()</methodname> accessor
            (or 'imageValue' configuration key). When the value set for the
            element matches the <property>imageValue</property>, then the accessor
            <methodname>isChecked()</methodname> will return <constant>TRUE</constant>.
        </para>

        <para>
            Image elements use the
            <link linkend="zend.form.standardDecorators.image">Image
                Decorator</link> for rendering, in addition to the standard Errors,
            HtmlTag, and Label decorators. You can optionally specify a tag to
            the <classname>Image</classname> decorator that will then wrap the image
            element.
        </para>
    </sect2>

    <sect2 id="zend.form.standardElements.multiCheckbox">
        <title>Zend_Form_Element_MultiCheckbox</title>

        <para>
            Often you have a set of related checkboxes, and you wish to group
            the results. This is much like a <link
                linkend="zend.form.standardElements.multiselect">Multiselect</link>,
            but instead of them being in a dropdown list, you need to show
            checkbox/value pairs.
        </para>

        <para>
            <classname>Zend_Form_Element_MultiCheckbox</classname> makes this a snap. Like
            all other elements extending the base Multi element, you can specify
            a list of options, and easily validate against that same list. The
            'formMultiCheckbox' view helper ensures that these are returned as
            an array in the form submission.
        </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>

        <para>
            You may manipulate the various checkbox options using the following
            methods:
        </para>

        <itemizedlist>
            <listitem>
                <para><methodname>addMultiOption($option, $value)</methodname></para>
            </listitem>

            <listitem>
                <para><methodname>addMultiOptions(array $options)</methodname></para>
            </listitem>

            <listitem>
                <para>
                    <methodname>setMultiOptions(array $options)</methodname> (overwrites existing
                    options)
                </para>
            </listitem>

            <listitem><para><methodname>getMultiOption($option)</methodname></para></listitem>
            <listitem><para><methodname>getMultiOptions()</methodname></para></listitem>
            <listitem><para><methodname>removeMultiOption($option)</methodname></para></listitem>
            <listitem><para><methodname>clearMultiOptions()</methodname></para></listitem>
        </itemizedlist>

        <para>
            To mark checked items, you need to pass an array of values to
            <methodname>setValue()</methodname>. The following will check the values "bar"
            and "bat":
        </para>

        <programlisting language="php"><![CDATA[
$element = new Zend_Form_Element_MultiCheckbox('foo', array(
    'multiOptions' => array(
        'foo' => 'Foo Option',
        'bar' => 'Bar Option',
        'baz' => 'Baz Option',
        'bat' => 'Bat Option',
    )
));

$element->setValue(array('bar', 'bat'));
]]></programlisting>

        <para>
            Note that even when setting a single value, you must pass an array.
        </para>
    </sect2>

    <sect2 id="zend.form.standardElements.multiselect">
        <title>Zend_Form_Element_Multiselect</title>

        <para>
            <acronym>XHTML</acronym> <emphasis>select</emphasis> elements allow a 'multiple'
            attribute, indicating multiple options may be selected for submission, instead
            of the usual one. <classname>Zend_Form_Element_Multiselect</classname> extends
            <link
                linkend="zend.form.standardElements.select">Zend_Form_Element_Select</link>,
            and sets the <property>multiple</property> attribute to 'multiple'. Like
            other classes that inherit from the base
            <classname>Zend_Form_Element_Multi</classname> class, you can manipulate the
            options for the select using:
        </para>

        <itemizedlist>
            <listitem>
                <para><methodname>addMultiOption($option, $value)</methodname></para>
            </listitem>

            <listitem>
                <para><methodname>addMultiOptions(array $options)</methodname></para>
            </listitem>

            <listitem>
                <para>
                    <methodname>setMultiOptions(array $options)</methodname> (overwrites existing
                    options)
                </para>
            </listitem>

            <listitem><para><methodname>getMultiOption($option)</methodname></para></listitem>
            <listitem><para><methodname>getMultiOptions()</methodname></para></listitem>
            <listitem><para><methodname>removeMultiOption($option)</methodname></para></listitem>
            <listitem><para><methodname>clearMultiOptions()</methodname></para></listitem>
        </itemizedlist>

        <para>
            If a translation adapter is registered with the form and/or element,
            option values will be translated for display purposes.
        </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>
    </sect2>

    <sect2 id="zend.form.standardElements.password">
        <title>Zend_Form_Element_Password</title>

        <para>
            Password elements are basically normal text elements -- except that
            you typically do not want the submitted password displayed in error
            messages or the element itself when the form is re-displayed.
        </para>

        <para>
            <classname>Zend_Form_Element_Password</classname> achieves this by calling
            <methodname>setObscureValue(true)</methodname> on each validator (ensuring that
            the password is obscured in validation error messages), and using
            the 'formPassword' view helper (which does not display the value
            passed to it).
        </para>
    </sect2>

    <sect2 id="zend.form.standardElements.radio">
        <title>Zend_Form_Element_Radio</title>

        <para>
            Radio elements allow you to specify several options, of which you
            need a single value returned. <classname>Zend_Form_Element_Radio</classname>
            extends the base <classname>Zend_Form_Element_Multi</classname> class,
            allowing you to specify a number of options, and then uses the
            <emphasis>formRadio</emphasis> view helper to display these.
        </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>

        <para>
            Like all elements extending the Multi element base class, the
            following methods may be used to manipulate the radio options
            displayed:
        </para>

        <itemizedlist>
            <listitem>
                <para><methodname>addMultiOption($option, $value)</methodname></para>
            </listitem>

            <listitem>
                <para><methodname>addMultiOptions(array $options)</methodname></para>
            </listitem>

            <listitem>
                <para>
                    <methodname>setMultiOptions(array $options)</methodname>
                    (overwrites existing options)
                </para>
            </listitem>

            <listitem><para><methodname>getMultiOption($option)</methodname></para></listitem>
            <listitem><para><methodname>getMultiOptions()</methodname></para></listitem>
            <listitem><para><methodname>removeMultiOption($option)</methodname></para></listitem>
            <listitem><para><methodname>clearMultiOptions()</methodname></para></listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.form.standardElements.reset">
        <title>Zend_Form_Element_Reset</title>

        <para>
            Reset buttons are typically used to clear a form, and are not part
            of submitted data. However, as they serve a purpose in the display,
            they are included in the standard elements.
        </para>

        <para>
            <classname>Zend_Form_Element_Reset</classname> extends <link
                linkend="zend.form.standardElements.submit">Zend_Form_Element_Submit</link>.
            As such, the label is used for the button display, and will be
            translated if a translation adapter is present. It utilizes only the
            'ViewHelper' and 'DtDdWrapper' decorators, as there should never be
            error messages for such elements, nor will a label be necessary.
        </para>
    </sect2>

    <sect2 id="zend.form.standardElements.select">
        <title>Zend_Form_Element_Select</title>

        <para>
            Select boxes are a common way of limiting to specific choices for a
            given form datum. <classname>Zend_Form_Element_Select</classname> allows you
            to generate these quickly and easily.
        </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>

        <para>
            As it extends the base Multi element, the following methods may be
            used to manipulate the select options:
        </para>

        <itemizedlist>
            <listitem>
                <para><methodname>addMultiOption($option, $value)</methodname></para>
            </listitem>

            <listitem>
                <para><methodname>addMultiOptions(array $options)</methodname></para>
            </listitem>

            <listitem>
                <para>
                    <methodname>setMultiOptions(array $options)</methodname>
                    (overwrites existing options)
                </para>
            </listitem>

            <listitem><para><methodname>getMultiOption($option)</methodname></para></listitem>
            <listitem><para><methodname>getMultiOptions()</methodname></para></listitem>
            <listitem><para><methodname>removeMultiOption($option)</methodname></para></listitem>
            <listitem><para><methodname>clearMultiOptions()</methodname></para></listitem>
        </itemizedlist>

        <para>
            <classname>Zend_Form_Element_Select</classname> uses the 'formSelect' view
            helper for decoration.
        </para>
    </sect2>

    <sect2 id="zend.form.standardElements.submit">
        <title>Zend_Form_Element_Submit</title>

        <para>
            Submit buttons are used to submit a form. You may use multiple
            submit buttons; you can use the button used to submit the form to
            decide what action to take with the data submitted.
            <classname>Zend_Form_Element_Submit</classname> makes this decisioning easy,
            by adding a <methodname>isChecked()</methodname> method; as only one button
            element will be submitted by the form, after populating or
            validating the form, you can call this method on each submit button
            to determine which one was used.
        </para>

        <para>
            <classname>Zend_Form_Element_Submit</classname> uses the label as the "value"
            of the submit button, translating it if a translation adapter is
            present. <methodname>isChecked()</methodname> checks the submitted value against
            the label in order to determine if the button was used.
        </para>

        <para>
            The <link
                linkend="zend.form.standardDecorators.viewHelper">ViewHelper</link>
            and <link
                linkend="zend.form.standardDecorators.dtDdWrapper">DtDdWrapper</link>
            decorators to render the element. No label decorator is used, as the
            button label is used when rendering the element; also, typically,
            you will not associate errors with a submit element.
        </para>
    </sect2>

    <sect2 id="zend.form.standardElements.text">
        <title>Zend_Form_Element_Text</title>

        <para>
            By far the most prevalent type of form element is the text element,
            allowing for limited text entry; it's an ideal element for most data
            entry. <classname>Zend_Form_Element_Text</classname> simply uses the
            'formText' view helper to display the element.
        </para>
    </sect2>

    <sect2 id="zend.form.standardElements.textarea">
        <title>Zend_Form_Element_Textarea</title>

        <para>
            Textareas are used when large quantities of text are expected, and
            place no limits on the amount of text submitted (other than maximum
            size limits as dictated by your server or <acronym>PHP</acronym>).
            <classname>Zend_Form_Element_Textarea</classname> uses the 'textArea' view
            helper to display such elements, placing the value as the content of
            the element.
        </para>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 tw=80 et:
-->