repo_zf1/documentation/manual/de/module_specs/Zend_Form-Forms.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 20115 -->
<!-- Reviewed: no -->
<sect1 id="zend.form.forms">
    <title>Erstellen von Form durch Verwendung von Zend_Form</title>

    <para>
        Die <classname>Zend_Form</classname> Klasse wird verwendet um Form Element, Anzeigegruppen
        und Unterforms zu gruppieren. Sie kann die folgenden Aktionen an diesen Elementen vornehmen:
    </para>

    <itemizedlist>
        <listitem><para>
            Prüfung, inklusive dem Empfang von Fehlercodes und Meldungen
        </para></listitem>

        <listitem><para>
            Werte behandeln, inklusive der Übermittlung von Elementen und dem Empfangen von beiden,
            gefilterten und ungefilterten Werten, von allen Elementen
        </para></listitem>

        <listitem><para>
            Iteration über alle Elemente in der Reihenfolge in der Sie eingegeben wurden oder
            basierend auf der Reihenfolge in der Hinweise von jedem Element empfangen werden
        </para></listitem>

        <listitem><para>
            Darstellung der kompletten Form, antweder über einen eigenen Dekorator der eigene
            Darstellungen durchführt oder durch die Iterierung über jedes Element in der Form
        </para></listitem>
    </itemizedlist>

    <para>
        Wärend Formen die mit <classname>Zend_Form</classname> erstellt werden komplex sein können,
        ist der warscheinlich beste Verwendungzweck eine einfache Form; die beste Verwendung ist für
        Rapid Application Development (RAD) und Prototyping.
    </para>

    <para>
        In der einfachsten Art, wird einfach ein Form Objekt instanziert:
    </para>

    <programlisting language="php"><![CDATA[
// Generelles Form Objekt:
$form = new Zend_Form();

// Eigenes Form Objekt:
$form = new My_Form()
]]></programlisting>

    <para>
        Es kann optional eine Instanz von <classname>Zend_Config</classname> oder ein Array
        übergeben werden, welches verwendet wird um den Status des Objektes zu setzen sowie
        potentiell neue Elemente zu erstellen:
    </para>

    <programlisting language="php"><![CDATA[
// Konfigurations Optionen übergeben:
$form = new Zend_Form($config);
]]></programlisting>

    <para>
        <classname>Zend_Form</classname> ist iterierbar und iteriert durch die Elemente,
        Anzeigegruppen und Subforms, indem es die Reihenfolge in der diese registriert wurde
        verwendet und jede Reihenfolge die der Index hat. Das ist nützlich in den Fällen in denen
        Elemente manuell in einer bestimmten Reihenfolge dargestellt werden sollen.
    </para>

    <para>
        <classname>Zend_Form</classname>'s Magie liegt in der Fähigkeit als Factory für Elemente und
        Anzeigegruppen zu arbeiten, genauso wie die Fähigkeit sich selbst durch Dekoratore
        darzustellen.
    </para>

    <sect2 id="zend.form.forms.plugins">
        <title>Plugin Loader</title>
        <para>
            <classname>Zend_Form</classname> verwendet
            <classname>Zend_Loader_PluginLoader</classname> um es Entwicklern zu erlauben Orte von
            alternativen Elementen und Dekoratoren zu spezifizieren. Jeder hat seinen eigenen mit
            Ihm assoziierten Plugin Loader, und generelle Zugriffspunkte werden verwendet um jeden
            zu empfangen und zu ändern.
        </para>

        <para>
            Die folgenden Loadertypen werden mit den verschiedenen Plugin Loader Methoden
            verwendet: 'element' und 'decorator'. Die Typnamen sind unabhängig von der
            Schreibweise.
        </para>

        <para>
            Die Methoden um mit Plugin Loader zu interagieren sind die folgenden:
        </para>

        <itemizedlist>
            <listitem><para>
                <methodname>setPluginLoader($loader, $type)</methodname>: $loader ist das Plugin
                Loader Objekt selbst. Das setzt den Plugin Loader für den gegebenen Typ zu dem neu
                spezifizierten Loader Objekt.
            </para></listitem>

            <listitem><para>
                <methodname>getPluginLoader($type)</methodname>: Empfängt den mit $type assoziierten
                Plugin Loader.
            </para></listitem>

            <listitem><para>
                <methodname>addPrefixPath($prefix, $path, $type = null)</methodname>: Fügt eine
                Präfix/Pfad Assoziation zum durch $type spezifizierten Loader hinzu. Wenn $type
                <constant>NULL</constant> ist, versucht es den Pfad allen Loadern hinzuzufügen,
                durch anhängen des Präfix an jedes "_Element" und "_Decorator"; und anhängen des
                Pfades an "Element/" und "Decorator/". Wenn man alle Extra Form Elementklassen in
                einer normalen Hierarchie sind, ist das die übliche Methode für das Setzen eines
                Basispräfix für Sie.
            </para></listitem>

            <listitem><para>
                <methodname>addPrefixPaths(array $spec)</methodname>: Erlaubt es viele Pfade auf
                einmal zu einem oder mehreren Plugin Loadern hinzuzufügen. Sie erwartet das jedes
                Array Element ein Array mit den Schlüsseln 'path', 'prefix' und 'type' ist.
            </para></listitem>
        </itemizedlist>

        <para>
            Zusätzlich kann ein Präfixpfad für alle Elemente und Anzeigegruppen die durch eine
            <classname>Zend_Form</classname> Instanz erstellt wurden, spezifiziert werden, durch
            Verwendung der folgenden Methoden:
        </para>

        <itemizedlist>
            <listitem><para>
                <methodname>addElementPrefixPath($prefix, $path, $type = null)</methodname>: Wie
                <methodname>addPrefixPath()</methodname>, nur das ein Klassenpräfix und ein Pfad
                spezifiziert werden muß. Wenn <varname>$type</varname> spezifiziert wurde, muß er
                einer der Plugin Loader Typen sein die in <classname>Zend_Form_Element</classname>
                spezifiziert sind; siehe das <link
                    linkend="zend.form.elements.loaders">Kapitel Element Plugins</link> für weitere
                Informationen über gültige <varname>$type</varname> Werte. Wenn kein
                <varname>$type</varname> spezifiziert wurde, nimmt diese Methode an das ein
                genereller Präfix für alle Typen spezifiziert wurde.
            </para></listitem>

            <listitem><para>
                <methodname>addDisplayGroupPrefixPath($prefix, $path)</methodname>: Wie
                <methodname>addPrefixPath()</methodname> nur das Klassenpräfix und ein Pfad
                spezifiziert werden muß; Trotzdem, da Anzeigegruppen nur Dekoratore als Plugin
                unterstützen, ist kein <varname>$type</varname> notwendig.
            </para></listitem>
        </itemizedlist>

        <para>
            Eigene Elemente und Dekoratore sind ein einfacher Weg um Funktionalitäten zwischen
            Forms zu teilen und eigene Funktionalitäten zu kapseln. Siehe das
            <link linkend="zend.form.elements.loaders.customLabel">Eigene Label Beispiel</link> in
            der Dokumentation über Elemente als Beispiel dafür, wie eigene Elemente als Ersatz für
            Standardklassen verwendet werden können.
        </para>
    </sect2>

    <sect2 id="zend.form.forms.elements">
        <title>Elemente</title>
        <para>
            <classname>Zend_Form</classname> bietet verschiedene Zugriffsmethoden für das Hinzufügen
            und Entfernen von Elementen aus einer Form. Diese können Instanzen von Elemente Objekten
            nehmen oder als Factories für das Instanzieren der Element Objekte selbe herhalten.
        </para>

        <para>
            Die grundsätzlichste Methode für das Hinzufügen eines Elements ist
            <methodname>addElement()</methodname>. Diese Methode kann entweder ein Objekt vom Typ
            <classname>Zend_Form_Element</classname> sein (oder einer Klasse die
            <classname>Zend_Form_Element</classname> erweitert), oder Argumente für das Erstellen
            eines neuen Elements -- inklusive dem Elementtyp, Namen, und jegliche
            Konfigurationsoption.
        </para>

        <para>
            Einige Beispiele:
        </para>

        <programlisting language="php"><![CDATA[
// Eine Instanz eines Elements verwenden:
$element = new Zend_Form_Element_Text('foo');
$form->addElement($element);

// Eine Factory verwenden
//
// Erstellt ein Element von Typ Zend_Form_Element_Text mit dem
// Namen 'foo':
$form->addElement('text', 'foo');

// Eine Label Option an das Element übergeben:
$form->addElement('text', 'foo', array('label' => 'Foo:'));
]]></programlisting>

        <note>
            <title>addElement() implementiert das Fluent Interface</title>

            <para>
                <methodname>addElement()</methodname> implementiert das Fluent Interface; das heißt
                es gibt das <classname>Zend_Form</classname> Objekt zurück und nicht das Element.
                Das wird getan um es zu erlauben das mehrere addElement() Methoden gekettet werden
                können oder andere Methoden die das Fluent Interface implementieren (alle Setzer in
                <classname>Zend_Form</classname> implementieren dieses Pattern).
            </para>

            <para>
                Wenn das Element zurückgegeben werden soll, muß stattdessen
                <methodname>createElement()</methodname> verwendet werden, welches anbei beschrieben
                wird. Trotzdem vorsicht, da <methodname>createElement()</methodname> das Element
                nicht der Form hinzufügt.
            </para>

            <para>
                <methodname>addElement()</methodname> verwendet intern
                <methodname>createElement()</methodname> um das Element zu erstellen bevor es der
                Form hinzugefügt wird.
            </para>
        </note>

        <para>
            Sobald ein Element der Form hinzugefügt wurde, kann es durch den Namen empfangen
            werden. Das kann entweder durch die Verwendung der <methodname>getElement()</methodname>
            Methode, oder durch Verwendung von Überladen um auf das Element als Objekteigenschaft
            zuzugreifen:
        </para>

        <programlisting language="php"><![CDATA[
// getElement():
$foo = $form->getElement('foo');

// Als Objekteigenschaft:
$foo = $form->foo;
]]></programlisting>

        <para>
            Fallweise, will man ein Element erstellen ohne es einer Form hinzuzufügen (zum
            Beispiel, wenn man die verschiedenen Plugin Pfade verwenden, aber das Objekt später zu
            einer Subform hinzufügen will). Die <methodname>createElement()</methodname> Methode
            erlaubt das:
        </para>

        <programlisting language="php"><![CDATA[
// $username wird ein Zend_Form_Element_Text Objekt:
$username = $form->createElement('text', 'username');
]]></programlisting>

        <sect3 id="zend.form.forms.elements.values">
            <title>Werte bekanntgeben und empfangen</title>

            <para>
                Nach der Prüfung einer Form, will man typischerweise die Werte empfangen damit
                andere Operationen durchgeführt werden können, wie das Aktualisieren einer
                Datenbank oder der Abfrage eines Web Services. Es können alle Werte für alle
                Elemente empfangen werden durch Verwendung von <methodname>getValues()</methodname>;
                <methodname>getValue($name)</methodname> erlabt es ausserdem den Wert eines
                einzelnen Elements durch den Elementnamen zu erhalten:
            </para>

            <programlisting language="php"><![CDATA[
// Alle Werte erhalten:
$values = $form->getValues();

// Nur den Wert des 'foo' Elements erhalten:
$value = $form->getValue('foo');
]]></programlisting>

            <para>
                Manchmal soll die Form mit spezifizierten Werte veröffentlicht werden bevor Sie
                dargestellt wird. Das kann entweder mit den <methodname>setDefaults()</methodname>
                oder <methodname>populate()</methodname> Methoden getan werden:
            </para>

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

            <para>
                Auf der anderen Seiten kann es gewünscht sein ein Formular, nach der Übertragung
                oder der Prüfung, zu löschen; das kann durch Verwendung der
                <methodname>reset()</methodname> Methode durchgeführt werden:
            </para>

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

        <sect3 id="zend.form.forms.elements.global">
            <title>Globale Operationen</title>

            <para>
                Fallweise wird man wollen das bestimmte Operationen alle Elemente beeinflussen.
                Übliche Szenarien enthalten das Setzen des Plugin Präfix Pfades für alle Elemente,
                Setzen der Dekoratore für alle Elemente, und das setzen von Filtern für alle
                Elemente. Als Beispiel:
            </para>

            <example id="zend.form.forms.elements.global.allpaths">
                <title>Setzen von Präfix Pfaden für alle Elemente</title>

                <para>
                    Präfix Pfade können für alle Elemente durch den Typ oder der Verwendung eines
                    globalen Präfix gesetzt werden. Einige Beispiele:
                </para>

                <programlisting language="php"><![CDATA[
// Einen gobalen Präfix setzen:
// Erstellt Pfade für die Präfixe My_Foo_Filter, My_Foo_Validate,
// und My_Foo_Decorator
$form->addElementPrefixPath('My_Foo', 'My/Foo/');

// Nur Filterpfade:
$form->addElementPrefixPath('My_Foo_Filter',
                            'My/Foo/Filter',
                            'filter');

// Nur Prüfungspfade:
$form->addElementPrefixPath('My_Foo_Validate',
                            'My/Foo/Validate',
                            'validate');

// Nur Dekoratorpfade:
$form->addElementPrefixPath('My_Foo_Decorator',
                            'My/Foo/Decorator',
                            'decorator');
]]></programlisting>
            </example>

            <example id="zend.form.forms.elements.global.decorators">
                <title>Dekoratore für alle Elemente setzen</title>

                <para>
                    Man kann Dekoratore für alle Elemente setzen.
                    <methodname>setElementDecorators()</methodname> akzeptiert ein Array von
                    Dekoratoren, wie <methodname>setDecorators()</methodname>, und überschreibt
                    jeden vorher gesetzten Dekorator in jedem Element. In diesem Beispiel wird der
                    Dekorator einfach auf einen ViewHelfer und ein Label gesetzt:
                </para>

                <programlisting language="php"><![CDATA[
$form->setElementDecorators(array(
    'ViewHelper',
    'Label'
));
]]></programlisting>
            </example>

            <example id="zend.form.forms.elements.global.decoratorsFilter">
                <title>Setzen von Dekoratoren für einige Elemente</title>

                <para>
                    Man kann Dekoratore auch für ein Subset von Elementen setzen, entweder durch
                    Ausbeziehung oder durch Ausgrenzung. Das zweite Argument von
                    <methodname>setElementDecorators()</methodname> kann ein Array von Elementnamen
                    sein; standardmäßig setzt so ein Array den spezifizierten Dekrator nur auf diese
                    Elemente. Man kann auch einen dritten Parameter angeben, ein Flag das anzeigt ob
                    diese Liste von Elementen einbezogen oder ausgegrenzt werden sollen. Wenn das
                    Flag <constant>FALSE</constant> ist, werden alle Elemente dekoriert
                    <emphasis>ausser</emphasis> denen die in der Liste übergeben wurden. Die normale
                    Verwendung der Methode besteht darin, das alle übergebenen Dekoratore alle
                    vorher gesetzten Dekoratore in jedem Element überschreiben.
                </para>

                <para>
                    Im folgenden Schnipsel, sagen wir das wir nur die ViewHelper und Label
                    Dekoratore für die 'foo' und 'bar' Elemente haben wollen:
                </para>

                <programlisting language="php"><![CDATA[
$form->setElementDecorators(
    array(
        'ViewHelper',
        'Label'
    ),
    array(
        'foo',
        'bar'
    )
);
]]></programlisting>

                <para>
                    Auf der anderen Seite zeigt dieses Schnipsel jetzt an das nur nur die ViewHelper
                    und Label Dekoratore für jedes Element verwenden wollen
                    <emphasis>ausgenommen</emphasis> die 'foo' und 'bar' Elemente:
                </para>

                <programlisting language="php"><![CDATA[
$form->setElementDecorators(
    array(
        'ViewHelper',
        'Label'
    ),
    array(
        'foo',
        'bar'
    ),
    false
);
]]></programlisting>
            </example>

            <note>
                <title>Einige Dekoratore sind für einige Elemente ungeeignet</title>

                <para>
                    Wärend <methodname>setElementDecorators()</methodname> wie eine gute Lösung
                    ausschaut gibt es einige Fälle in denen es zu unerwarteten Ergebnissen führen
                    kann. Zum Beispiel verwenden die verschiedenen Button Elemente (Submit, Button,
                    Reset) aktuell das Label als Wert des Buttons, und verwenden nur den
                    ViewHelper und DtDdWrapper Dekorator -- was zusätzliche Labels, Fehler und
                    Hinweise für die Darstellung verhindert. Das obige Beispiel würde einige
                    Inhalte (das Label) für Button Elemente duplizieren.
                </para>

                <para>
                    Man kann das Enthalten/Ausnehmen Array verwenden um dieses Problem, wie im
                    vorherigen Beispiel gezeigt, zu umgehen.
                </para>

                <para>
                    Diese Methode sollte also weise verwendet werden und man sollte bedenken
                    das man einige Dekoratore von Elementen händisch ändern muss damit
                    ungewollte Ausgaben verhindert werden.
                </para>
            </note>

            <example id="zend.form.forms.elements.global.filters">
                <title>Filter für alle Elemente setzen</title>

                <para>
                    In einigen Fällen will man den selben Filter auf alle Elemente anwenden; ein
                    üblicher Fall ist es alle Werte zu <methodname>trim()</methodname>men:
                </para>

                <programlisting language="php"><![CDATA[
$form->setElementFilters(array('StringTrim'));
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="zend.form.forms.elements.methods">
            <title>Methoden für die Interaktion mit Elementen</title>

            <para>
                Die folgenden Methoden können verwendet werden um mit Elementen zu interagieren:
            </para>

            <itemizedlist>
                <listitem><para>
                    <methodname>createElement($element, $name = null, $options = null)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>addElement($element, $name = null, $options = null)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>addElements(array $elements)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>setElements(array $elements)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>getElement($name)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>getElements()</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>removeElement($name)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>clearElements()</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>setDefaults(array $defaults)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>setDefault($name, $value)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>getValue($name)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>getValues()</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>getUnfilteredValue($name)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>getUnfilteredValues()</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>setElementFilters(array $filters)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>setElementDecorators(array $decorators)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>addElementPrefixPath($prefix, $path, $type = null)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>addElementPrefixPaths(array $spec)</methodname>
                </para></listitem>
            </itemizedlist>
        </sect3>
    </sect2>

    <sect2 id="zend.form.forms.displaygroups">
        <title>Anzeigegruppen</title>

        <para>
            Anzeigegruppen sind ein Weg um virtuell Gruppierungen von Elementen für Anzeigezwecke
            zu erstellen. Alle Elemente bleiben durch Ihren Namen in der Form zugreifbar, aber wenn
            die Form iteriert oder dargestellt wird, werden alle Elemente in Anzeigegruppen
            gemeinsam dargestellt. Üblicherweise wird das für die Gruppierung von Elementen in
            Fieldsets verwendet.
        </para>

        <para>
            Die Basisklasse für Anzeigegruppen ist <classname>Zend_Form_DisplayGroup</classname>.
            Wärend Sie direkt Instanziert werden kann, ist es normalerweise am besten die
            <methodname>addDisplayGroup()</methodname> Methode von <classname>Zend_Form</classname>
            zu verwenden um das zu erledigen. Diese Methode nimmt ein Array von Elementen als erstes
            Argument, und einen Namen für die Anzeigegruppe als zweites Argument. Es kann optional
            ein Array von Optionen oder ein <classname>Zend_Config</classname> Objekt als drittes
            Argument übergeben werden.
        </para>

        <para>
            Angenommen das die Elemente 'username' und 'passwort' bereits in der Form gesetzt
            wurden. Dann würde der folgende Code diese Elemente in einer 'login' Anzeigegruppe
            gruppieren:
        </para>

        <programlisting language="php"><![CDATA[
$form->addDisplayGroup(array('username', 'password'), 'login');
]]></programlisting>

        <para>
            Auf Displaygruppen kann mithilfe der <methodname>getDisplayGroup()</methodname> Methode
            zugegriffen werden, oder über Überladung inden der Name der Anzeigegruppe verwendet
            wird:
        </para>

        <programlisting language="php"><![CDATA[
// getDisplayGroup() verwenden:
$login = $form->getDisplayGroup('login');

// Überladen verwenden:
$login = $form->login;
]]></programlisting>

        <note>
            <title>Standarddekoratore müssen nicht geladen werden</title>

            <para>
                Standardmäßig werden die Standarddekoratore wärend der Initialisierung des Objektes
                geladen. Das kann durch die Übergabe der 'disableLoadDefaultDecorators' Option, bei
                der Erstellung der Anzeigegruppe, deaktiviert werden:
            </para>

            <programlisting language="php"><![CDATA[
$form->addDisplayGroup(
    array('foo', 'bar'),
    'foobar',
    array('disableLoadDefaultDecorators' => true)
);
]]></programlisting>

            <para>
                Diese Option kann mit jeder anderen Option gemischt werden die übergeben wird,
                sowohl als Array Option als auch in einem <classname>Zend_Config</classname> Objekt.
            </para>
        </note>

        <sect3 id="zend.form.forms.displaygroups.global">
            <title>Globale Operationen</title>

            <para>
                Wie bei den Elementen gibt es einige Operationen welche alle Anzeigegruppen
                beeinflussen; diese inkludieren das Setzen von Dekoratoren und Setzen des Plugin
                Pfades in denen nach Dekoratoren nachgesehen werden soll.
            </para>

            <example id="zend.form.forms.displaygroups.global.paths">
                <title>Setzen des Dekorator Präfix Pfades für alle Anzeigegruppen</title>

                <para>
                    Standardmäßig erben Anzeigegruppen die Dekorator Pfade welche die Form
                    verwendet; wenn trotzdem in alternativen Orten nachgeschaut werden soll kann die
                    <methodname>addDisplayGroupPrefixPath()</methodname> Methode verwendet werden.
                </para>

                <programlisting language="php"><![CDATA[
$form->addDisplayGroupPrefixPath('My_Foo_Decorator', 'My/Foo/Decorator');
]]></programlisting>
            </example>

            <example id="zend.form.forms.displaygroups.global.decorators">
                <title>Setzen von Dekoratoren für alle Anzeigegruppen</title>

                <para>
                    Es können Dekoratore für alle Anzeigegruppen gesetzt werden.
                    <methodname>setDisplayGroupDecorators()</methodname> akzeptiert ein Array von
                    Dekoratoren, wie <methodname>setDecorators()</methodname>, und überschreibt alle
                    vorher gesetzten Dekoratore in jeder Anzeigegruppe. In diesem Beispiel setzen
                    wir die Dekoratore einfach auf ein Fieldset (der FormElements Dekorator ist
                    notwendig um sicherzustellen das die Elemente iterierbar sind):
                </para>

                <programlisting language="php"><![CDATA[
$form->setDisplayGroupDecorators(array(
    'FormElements',
    'Fieldset'
));
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="zend.form.forms.displaygroups.customClasses">
            <title>Eigene Anzeigegruppen Klassen verwenden</title>

            <para>
                Standardmäßig verwendet <classname>Zend_Form</classname> die
                <classname>Zend_Form_DisplayGroup</classname> Klasse für Anzeigegruppen. Man kann
                diese Klasse erweitern um eigene Funktionalitäten anzubieten.
                <methodname>addDisplayGroup()</methodname> erlaubt es nicht eine konkrete Instanz zu
                übergeben, aber sie erlaubt es eine Klasse zu spezifizieren die als eine
                Ihrer Optionen verwendet wird, indem der 'displayGroupClass' Schlüssel verwendet
                wird:
            </para>

            <programlisting language="php"><![CDATA[
// Verwenden der 'My_DisplayGroup' Klasse
$form->addDisplayGroup(
    array('username', 'password'),
    'user',
    array('displayGroupClass' => 'My_DisplayGroup')
);
]]></programlisting>

            <para>
                Wenn die Klasse noch nicht geladen wurde, versucht <classname>Zend_Form</classname>
                das zu tun, indem <classname>Zend_Loader</classname> verwendet wird.
            </para>

            <para>
                Es kann auch eine eine Standardklasse für Anzeigegruppen definiert werden die mit
                der Form zu verwenden ist, sodas alle Anzeigegrupen die mit dem Form Objekt
                erstellt werden diese Klasse verwenden:
            </para>

            <programlisting language="php"><![CDATA[
// Verwenden der Klasse 'My_DisplayGroup' für alle Anzeigegruppen:
$form->setDefaultDisplayGroupClass('My_DisplayGroup');
]]></programlisting>

            <para>
                Diese Einstellung kann in Konfigurationen als 'defaultDisplayGroupClass'
                spezifiziert werden, und wird früh geladen um sicherzustellen das alle
                Anzeigegruppen diese Klasse verwenden.
            </para>
        </sect3>

        <sect3 id="zend.form.forms.displaygroups.interactionmethods">
            <title>Methoden für die Interaktion mit Anzeigegruppen</title>

            <para>
                Die folgenden Methoden können verwendet werden um mit Anzeigegruppen zu
                interagieren:
            </para>

            <itemizedlist>
                <listitem><para>
                    <methodname>addDisplayGroup(array $elements, $name, $options =
                        null)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>addDisplayGroups(array $groups)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>setDisplayGroups(array $groups)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>getDisplayGroup($name)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>getDisplayGroups()</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>removeDisplayGroup($name)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>clearDisplayGroups()</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>setDisplayGroupDecorators(array $decorators)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>addDisplayGroupPrefixPath($prefix, $path)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>setDefaultDisplayGroupClass($class)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>getDefaultDisplayGroupClass($class)</methodname>
                </para></listitem>
            </itemizedlist>
        </sect3>

        <sect3 id="zend.form.forms.displaygroups.methods">
            <title>Methoden von Zend_Form_DisplayGroup</title>

            <para>
                <classname>Zend_Form_DisplayGroup</classname> hat die folgenden Methoden, gruppiert
                nach Typ:
            </para>

            <itemizedlist>
                <listitem><para>Konfiguration:</para>
                    <itemizedlist>
                        <listitem>
                            <para><methodname>setOptions(array $options)</methodname></para>
                        </listitem>

                        <listitem>
                            <para><methodname>setConfig(Zend_Config $config)</methodname></para>
                        </listitem>
                    </itemizedlist>
                </listitem>

                <listitem><para>Metadaten:</para>
                    <itemizedlist>
                        <listitem>
                            <para><methodname>setAttrib($key, $value)</methodname></para>
                        </listitem>

                        <listitem>
                            <para><methodname>addAttribs(array $attribs)</methodname></para>
                        </listitem>

                        <listitem>
                            <para><methodname>setAttribs(array $attribs)</methodname></para>
                        </listitem>

                        <listitem><para><methodname>getAttrib($key)</methodname></para></listitem>

                        <listitem><para><methodname>getAttribs()</methodname></para></listitem>

                        <listitem>
                            <para><methodname>removeAttrib($key)</methodname></para>
                        </listitem>

                        <listitem><para><methodname>clearAttribs()</methodname></para></listitem>

                        <listitem><para><methodname>setName($name)</methodname></para></listitem>

                        <listitem><para><methodname>getName()</methodname></para></listitem>

                        <listitem>
                            <para><methodname>setDescription($value)</methodname></para>
                        </listitem>

                        <listitem><para><methodname>getDescription()</methodname></para></listitem>

                        <listitem>
                            <para><methodname>setLegend($legend)</methodname></para>
                        </listitem>

                        <listitem><para><methodname>getLegend()</methodname></para></listitem>

                        <listitem><para><methodname>setOrder($order)</methodname></para></listitem>

                        <listitem><para><methodname>getOrder()</methodname></para></listitem>
                    </itemizedlist>
                </listitem>

                <listitem><para>Elemente:</para>
                    <itemizedlist>
                        <listitem>
                            <para>
                                <methodname>createElement($type, $name, array $options =
                                    array())</methodname>
                            </para>
                        </listitem>

                        <listitem>
                            <para>
                                <code>addElement($typeOrElement, $name, array $options =
                                array())</code>
                            </para>
                        </listitem>

                        <listitem>
                            <para><methodname>addElements(array $elements)</methodname></para>
                        </listitem>

                        <listitem>
                            <para><methodname>setElements(array $elements)</methodname></para>
                        </listitem>

                        <listitem><para><methodname>getElement($name)</methodname></para></listitem>

                        <listitem><para><methodname>getElements()</methodname></para></listitem>

                        <listitem>
                            <para><methodname>removeElement($name)</methodname></para>
                        </listitem>

                        <listitem><para><methodname>clearElements()</methodname></para></listitem>
                    </itemizedlist>
                </listitem>

                <listitem><para>Plugin Loader:</para>
                    <itemizedlist>
                        <listitem>
                            <para>
                                <methodname>setPluginLoader(Zend_Loader_PluginLoader
                                    $loader)</methodname>
                            </para>
                        </listitem>

                        <listitem><para><methodname>getPluginLoader()</methodname></para></listitem>

                        <listitem>
                            <para><methodname>addPrefixPath($prefix, $path)</methodname></para>
                        </listitem>

                        <listitem>
                            <para><methodname>addPrefixPaths(array $spec)</methodname></para>
                        </listitem>
                    </itemizedlist>
                </listitem>

                <listitem><para>Dekoratore:</para>
                    <itemizedlist>
                        <listitem>
                            <para>
                                <methodname>addDecorator($decorator, $options = null)</methodname>
                            </para>
                        </listitem>

                        <listitem>
                            <para><methodname>addDecorators(array $decorators)</methodname></para>
                        </listitem>

                        <listitem>
                            <para><methodname>setDecorators(array $decorators)</methodname></para>
                        </listitem>

                        <listitem>
                            <para><methodname>getDecorator($name)</methodname></para>
                        </listitem>

                        <listitem><para><methodname>getDecorators()</methodname></para></listitem>

                        <listitem>
                            <para><methodname>removeDecorator($name)</methodname></para>
                        </listitem>

                        <listitem><para><methodname>clearDecorators()</methodname></para></listitem>
                    </itemizedlist>
                </listitem>

                <listitem><para>Darstellung:</para>
                    <itemizedlist>
                        <listitem>
                            <para>
                                <methodname>setView(Zend_View_Interface $view = null)</methodname>
                            </para>
                        </listitem>

                        <listitem><para><methodname>getView()</methodname></para></listitem>

                        <listitem>
                            <para>
                                <methodname>render(Zend_View_Interface $view = null)</methodname>
                            </para>
                        </listitem>
                    </itemizedlist>
                </listitem>

                <listitem><para>I18n:</para>
                    <itemizedlist>
                        <listitem>
                            <para>
                                <code>setTranslator(Zend_Translate_Adapter $translator =
                                null)</code>
                            </para>
                        </listitem>

                        <listitem><para><methodname>getTranslator()</methodname></para></listitem>

                        <listitem>
                            <para><methodname>setDisableTranslator($flag)</methodname></para>
                        </listitem>

                        <listitem>
                            <para><methodname>translatorIsDisabled()</methodname></para>
                        </listitem>
                    </itemizedlist>
                </listitem>
            </itemizedlist>
        </sect3>
    </sect2>

    <sect2 id="zend.form.forms.subforms">
        <title>Subformen</title>

        <para>
            Subformen haben unterschiedliche Zwecke:
        </para>

        <itemizedlist>
            <listitem><para>
                Erstellung von logischen Element Gruppen. Da Subformen einfach Formen sind, können
                Sie auch wie individuelle Einheiten geprüft werden.
            </para></listitem>

            <listitem><para>
                Erstellung von Multi-Seiten Formen. Da Subformen einfach Formen sind, kann eine
                separate Subform pro Seite angezeigt werden, um Multi-Seiten Formen zu bauen in
                denen jede Form seine eigene Prüflogik besitzt. Nur sobald alle Subformen
                geprüft wurden würde die Form als komplett angenommen werden.
            </para></listitem>

            <listitem><para>
                Anzeige Gruppierungen. Wie Anzeigegruppen, können Subformen, wenn Sie als Teil
                einer größeren Form dargestellt werden, verwendet werden um Elemente zu gruppieren.
                Trotzdem muß darauf geachtet werden dass das Hauptform Objekt keine Ahnung von den
                Elementen in Subformen besitzt.
            </para></listitem>
        </itemizedlist>

        <para>
            Eine Subform kann ein <classname>Zend_Form</classname> Objekt sein, oder typischerweise
            ein <classname>Zend_Form_SubForm</classname> Objekt. Das zweitere enthält Dekoratore die
            für das Einfügen in größere Formen passen (z.B. gibt es keine zusätzlichen HTML form
            Tags aus, gruppiert aber Elemente). Um eine Subform anzuhängen, muß diese einfach der
            Form hinzugefügt und ein Name vergeben werden:
        </para>

        <programlisting language="php"><![CDATA[
$form->addSubForm($subForm, 'subform');
]]></programlisting>

        <para>
            Eine Subform kann empfangen werden indem entweder
            <methodname>getSubForm($name)</methodname> oder Überladung mithilfe des Namens der
            Subform verwendet wird:
        </para>

        <programlisting language="php"><![CDATA[
// Verwenden von getSubForm():
$subForm = $form->getSubForm('subform');

// Verwenden von Überladen:
$subForm = $form->subform;
]]></programlisting>

        <para>
            Subformen sind bei der Iteration der Form enthalten, aber die Elemente die Sie enthalten
            nicht.
        </para>

        <sect3 id="zend.form.forms.subforms.global">
            <title>Globale Operationen</title>

            <para>
                Wie Elemente und Anzeigegruppen. gibt es einige Operationen für die es notwendig
                ist alle Subformen zu bearbeiten. Anders als Anzeigegruppen und Elemente, erben
                Subformen die meisten Funktionalitäten vom Hauptform Objekt, und die einzige
                wirklich Operation die durchgeführt werden sollte, ist das Setzen der Dekoratore
                für Subformen. Für diesen Zweck, gibt es die
                <methodname>setSubFormDecorators()</methodname> Methode. Im nächsten Beispiel setzen
                wir den Dekorator für alle Subformen einfach auf ein Fieldset (der FormElements
                Dekorator wird benötigt um sicherzustellen das seine Elemente iterierbar sind):
            </para>

            <programlisting language="php"><![CDATA[
$form->setSubFormDecorators(array(
    'FormElements',
    'Fieldset'
));
]]></programlisting>
        </sect3>

        <sect3 id="zend.form.forms.subforms.methods">
            <title>Methoden für die Interaktion mit Subfomen</title>

            <para>
                Die folgenden Meothden können verwendet werden um mit Subformen zu interagieren:
            </para>

            <itemizedlist>
                <listitem><para>
                    <methodname>addSubForm(Zend_Form $form, $name, $order = null)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>addSubForms(array $subForms)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>setSubForms(array $subForms)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>getSubForm($name)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>getSubForms()</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>removeSubForm($name)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>clearSubForms()</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>setSubFormDecorators(array $decorators)</methodname>
                </para></listitem>
            </itemizedlist>
        </sect3>
    </sect2>

    <sect2 id="zend.form.forms.metadata">
        <title>Metadaten und Attribute</title>

        <para>
            Wärend die Nützlichkeit von Formen primär von den Elementen die Sie enthalten her
            rührt, enthhalten Sie auch anderen Metadaten, wie einen Namen (oft verwendet als
            eindeutige ID im HTML Markup); die Aktion und Methode der Form; die Anzahl an
            Elementen, Gruppen, und Subformen die Sie enthält; und sonstige Metadaten (die
            normalerweise verwendet werden um HTML Attribute für das Form Tag selbst zu setzen).
        </para>

        <para>
            Der Name der Form kann mithilfe der name Zugriffsmethoden gesetzt und empfangen werden:
        </para>

        <programlisting language="php"><![CDATA[
// Den Namen setzen:
$form->setName('registration');

// Den Namen empfangen:
$name = $form->getName();
]]></programlisting>

        <para>
            Um die Aktion (URL zu der die Form übermittelt) und Methode (Methode mit der
            übermittelt werden soll, 'POST' oder 'GET') zu setzen, können die Zugriffsmethoden für
            action und method verwendet werden:
        </para>

        <programlisting language="php"><![CDATA[
// action und method setzen:
$form->setAction('/user/login')
     ->setMethod('post');
]]></programlisting>

        <para>
            Man kann auch den Encoding Typ des Formulars spezifizieren indem die Enctype
            Zugriffsmethode verwendet wird. <classname>Zend_Form</classname> definiert zwei
            Konstanten, <constant>Zend_Form::ENCTYPE_URLENCODED</constant> und
            <constant>Zend_Form::ENCTYPE_MULTIPART</constant>, die den Werten
            'application/x-www-form-urlencoded' und 'multipart/form-data' entsprechen; trotzdem kann
            das auf jeden gewünschten Encodingtyp gesetzt werden.
        </para>

        <programlisting language="php"><![CDATA[
// Setzt die Aktion, Methoden, und Enctype:
$form->setAction('/user/login')
     ->setMethod('post')
     ->setEnctype(Zend_Form::ENCTYPE_MULTIPART);
]]></programlisting>

        <note>
            <para>
                Methode, Aktion und Encodingtyp werden nur intern für die Darstellung verwendet,
                und nicht für irgendeine Art von Prüfung.
            </para>
        </note>

        <para>
            <classname>Zend_Form</classname> implementiert das <code>Countable</code> Interface,
            welches es erlaubt es als Argument fürs Zählen zu übergeben:
        </para>

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

        <para>
            Das Setzen von eigenen Metadaten wird durch die attribs Zugriffsmethode durchgeführt.
            Da Überladen in <classname>Zend_Form</classname> verwendet wird um auf Elemente,
            Anzeigegruppen, und Subformen zuzugreifen ist das die einzige Methode für den Zugriff
            auf Metadaten.
        </para>

        <programlisting language="php"><![CDATA[
// Setzen von Attributen:
$form->setAttrib('class', 'zend-form')
     ->addAttribs(array(
         'id'       => 'registration',
         'onSubmit' => 'validate(this)',
     ));

// Empfangen von Attributen:
$class = $form->getAttrib('class');
$attribs = $form->getAttribs();

// Entfernen eines Attributes:
$form->removeAttrib('onSubmit');

// Löschen aller Attribute:
$form->clearAttribs();
]]></programlisting>
    </sect2>

    <sect2 id="zend.form.forms.decorators">
        <title>Dekoratore</title>

        <para>
            Das Erstellen des Markups für eine Form ist oft ein zeitintensiver Arbeitsschritt,
            speziell wenn man plant das selbe Markup wiederzuverwenden um Dinge zu zeigen wie
            Prüffehler, übermittelte Werte, usw. <classname>Zend_Form</classname>'s Antwort hierfür
            sind <emphasis>Dekoratore</emphasis>.
        </para>

        <para>
            Dekoratore für <classname>Zend_Form</classname> Objekte können verwendet werden um eine
            Form darzustellen. Der FormElements Dekorator iteriert durch alle Elemente in einer Form
            -- Elemente, Anzeigegruppen, und Subformen -- stellt sie dar, und gibt das Ergebnis
            zurück. Zusätzliche Dekoratore können dann verwendet werden um diese Inhalte zu
            wrappen, sie anzufügen oder sie voranzustellen.
        </para>

        <para>
            Die Standarddekoratore für <classname>Zend_Form</classname> sind FormElemente, HtmlTag
            (wrappt in einer Definitionsliste), und Form; der entsprechende Code für deren
            Erstellung ist wie folgt:
        </para>

        <programlisting language="php"><![CDATA[
$form->setDecorators(array(
    'FormElements',
    array('HtmlTag', array('tag' => 'dl')),
    'Form'
));
]]></programlisting>

        <para>
            Das erstellt eine Ausgabe wie die folgende:
        </para>

        <programlisting language="html"><![CDATA[
<form action="/form/action" method="post">
<dl>
...
</dl>
</form>
]]></programlisting>

        <para>
            Jegliche Attribute die auf dem Form Objekt gesetzt sindwerden als HTML Attribute des
            <code>&lt;form&gt;</code> Tags verwendet.
        </para>

        <note>
            <title>Standarddekoratore müssen nicht geladen werden</title>

            <para>
                Standardmäßig werden die Standarddekoratore wärend der Initialisierung des Objektes
                geladen. Das kann durch die Übergabe der 'disableLoadDefaultDecorators' Option, bei
                der Erstellung der Anzeigegruppe, deaktiviert werden:
            </para>

            <programlisting language="php"><![CDATA[
$form = new Zend_Form(array('disableLoadDefaultDecorators' => true));
]]></programlisting>

            <para>
                Diese Option kann mit jeder anderen Option gemischt werden die übergeben wird,
                sowohl als Array Option als auch in einem <classname>Zend_Config</classname> Objekt.
            </para>
        </note>

        <note>
            <title>Verwenden mehrerer Dekoratore des gleichen Typs</title>

            <para>
                Intern verwendet <classname>Zend_Form</classname> eine Dekorator Klasse als
                Mechsnismus für das nachsehen wenn Dekoratore empfangen werden. Als Ergebnis können
                mehrere Dekoratore nicht zur gleichen Zeit registriert werden; nachfolgende
                Dekoratore würden einfach die vorher existierenden überschreiben.
            </para>

            <para>
                Um das zu umgehen können Aliase verwendet werden. Statt der Übergabe eines
                Dekorators oder eines Dekoratornamens als erstes Argument an
                <methodname>addDecorator()</methodname>, kann ein Array mit einem einzelnen Argument
                übergeben werden, mit dem Alias der auf das Dekorator Objekt oder den Namen zeigt:
            </para>

            <programlisting language="php"><![CDATA[
// Alias zu 'FooBar':
$form->addDecorator(array('FooBar' => 'HtmlTag'), array('tag' => 'div'));

// Und Ihn später empfangen:
$form = $element->getDecorator('FooBar');
]]></programlisting>

            <para>
                In den <methodname>addDecorators()</methodname> und
                <methodname>setDecorators()</methodname> Methoden muß die 'decorator' Option im
                Array übergeben werden das den Dekorator repräsentiert:
            </para>

            <programlisting language="php"><![CDATA[
// Zwei 'HtmlTag' Dekoratore hinzufügen und einen mit 'FooBar' benennen:
$form->addDecorators(
    array('HtmlTag', array('tag' => 'div')),
    array(
        'decorator' => array('FooBar' => 'HtmlTag'),
        'options' => array('tag' => 'dd')
    ),
);

// Und Sie später empfangen:
$htmlTag = $form->getDecorator('HtmlTag');
$fooBar  = $form->getDecorator('FooBar');
]]></programlisting>
        </note>

        <para>
            Man kann eigene Dekoratore für die Erzeugung der Form erstellen. Ein üblicher Grund
            hierfür ist, wenn man das exakte HTML weiß das man verwenden will; der Dekorator könnte
            das exakte HTML erstellen und es einfach zurückgeben, wobei potentiell die Dekoratore
            der individuellen Elemente oder Anzeigegruppen verwendet werden.
        </para>

        <para>
            Die folgenden Methoden können verwendet werden um mit Dekoratoren zu interagieren:
        </para>

        <itemizedlist>
                <listitem><para>
                    <methodname>addDecorator($decorator, $options = null)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>addDecorators(array $decorators)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>setDecorators(array $decorators)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>getDecorator($name)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>getDecorators()</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>removeDecorator($name)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>clearDecorators()</methodname>
                </para></listitem>
        </itemizedlist>

        <para>
            <classname>Zend_Form</classname> verwendet auch das Überladen um die Darstellung von
            speziellen Dekoratoren zu erlauben. <methodname>__call()</methodname> interagiert mit
            Methoden die mit dem Text 'render' beginnen und verwendet den Rest des Methodennamens
            um nach einem Dekorator zu suchen; wenn er gefunden wird, wird dieser
            <emphasis>einzelne</emphasis> Dekorator dargestellt. Jedes Argument das dem
            Methodenaufruf übergeben wird, wird als Inhalt an die <methodname>render()</methodname>
            Methode des Dekorators übergeben. Als Beispiel:
        </para>

        <programlisting language="php"><![CDATA[
// Stellt nur den FormElements Dekorator dar:
echo $form->renderFormElements();

// Stell nur den Fieldset Dekorator dar, und übergibt Inhalte:
echo $form->renderFieldset("<p>Das ist der Fieldset Inhalt</p>");
]]></programlisting>

        <para>
            Wenn der Dekorator nicht existiert, wird eine Exception geworfen.
        </para>
    </sect2>

    <sect2 id="zend.form.forms.validation">
        <title>Prüfung</title>

        <para>
            Ein primärer Verwendungszweck für Forms ist die Überprüfung von übermittelten Daten.
            <classname>Zend_Form</classname> erlaubt es eine komplette Form, eine teilweise Form,
            oder Antworten von XmlHttpRequests (AJAX) zu prüfen. Wenn die übertragenen Daten nicht
            gültig sind, hat es Methoden für das Empfangen der verschiedenen Fehlercodes und
            Nachrichten für Elemente und Subformen.
        </para>

        <para>
            Um eine ganze Form zu prüfen, kann die <methodname>isValid()</methodname> Methode
            verwendet werden:
        </para>

        <programlisting language="php"><![CDATA[
if (!$form->isValid($_POST)) {
    // Prüfung fehlgeschlagen
}
]]></programlisting>

        <para>
            <methodname>isValid()</methodname> prüft jedes benötigte Element, und jedes nicht
            benötigte Element das in den übermittelten Daten enthalten ist.
        </para>

        <para>
            Manchmal muß nur ein Subset der Daten geprüft werden; dafür kann
            <methodname>isValidPartial($data)</methodname> verwendet werden:
        </para>

        <programlisting language="php"><![CDATA[
if (!$form->isValidPartial($data)) {
    // Prüfung fehlgeschlagen
}
]]></programlisting>

        <para>
            <methodname>isValidPartial()</methodname> versucht nur die Teile zu prüfen für die es
            passende Elemente gibt; wenn ein Element nicht in den Daten repräsentiert ist, wird es
            übersprungen.
        </para>

        <para>
            Wenn Elemente oder Gruppen von Elementen für eine <acronym>AJAX</acronym> Anfrage
            geprüft werden, wird üblicherweise ein Subset der Form geprüft, und die Antwort in
            <acronym>JSON</acronym> zurückgegeben. <methodname>processAjax()</methodname> führt das
            präzise durch:
        </para>

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

        <para>
            Man kann dann einfach die <acronym>JSON</acronym> Antwort an den Client senden. Wenn die
            Form gültig ist, wird das eine boolsche <constant>TRUE</constant> Antwort sein. Wenn
            nicht, wird es ein Javascript Objekt sein das Schlüssel/Nachricht Paare enthält, wobei
            jede Nachricht 'message' ein Array von Prüf-Fehlermeldungen enthält.
        </para>

        <para>
            Für Forms bei denen die Prüfung fehlschlägt, können beide, Fehlercodes und
            Fehlermeldung empfangen werden, indem <methodname>getErrors()</methodname> und
            <methodname>getMessages()</methodname> verwendet werden:
        </para>

        <programlisting language="php"><![CDATA[
$codes = $form->getErrors();
$messages = $form->getMessages();
]]></programlisting>

        <note>
            <para>
                Da die Nachrichten die von <methodname>getMessages()</methodname> zurückgegeben
                werden in einem Array von Fehlercode/Nachricht Paaren sind, wird
                <methodname>getErrors()</methodname> normalerweise nicht benötigt.
            </para>
        </note>

        <para>
            Codes und Fehlermeldungen kann man für individuelle Elemente erhalten indem einfach
            der Name des Elements an jede übergeben wird:
        </para>

        <programlisting language="php"><![CDATA[
$codes = $form->getErrors('username');
$messages = $form->getMessages('username');
]]></programlisting>

        <note>
            <para>
                Notiz: Wenn Elemente geprüft werden, sendet <classname>Zend_Form</classname> ein
                zweites Argument zu jeder <methodname>isValid()</methodname> Methode der Elemente:
                Das Array der Daten die geprüft werden sollen. Das kann von individuellen Prüfern
                verwendet werden um Ihnen zu erlauben andere übertragene Werte zu verwenden wenn die
                Gültigkeit der Daten ermittelt wird. Ein Beispiel wäre eine Registrations Form die
                beide benötigt, ein Passwort und eine Passwort Bestätigung; das Passwort Element
                könnte die Passwort Bestätigung als Teil seiner Prüfung verwenden.
            </para>
        </note>

        <sect3 id="zend.form.forms.validation.errors">
            <title>Selbst definierte Fehlermeldungen</title>

            <para>
                Von Zeit zu Zeit ist es gewünscht ein oder mehrere spezielle Fehlermeldungen zu
                spezifizieren die statt den Fehlermeldungen verwendet werden sollen die von den
                Validatoren verwendet werden die dem Element angehängt sind. Zusätzlich will man von
                Zeit zu Zeit ein Element selbst als ungültig markieren. Diese Funktionalität ist
                über die folgenden Methoden ermöglicht.
            </para>

            <itemizedlist>
                <listitem><para>
                    <methodname>addErrorMessage($message)</methodname>: Fügt eine Fehlermeldung
                    hinzu die bei Form-Überprüfungs-Fehlern angezeigt wird. Sie kann mehr als einmal
                    aufgerufen werden, und neue Meldungen werden dem Stack angehängt.
                </para></listitem>

                <listitem><para>
                    <methodname>addErrorMessages(array $messages)</methodname>: Fügt mehrere
                    Fehlermeldungen hinzu die bei Form-Überprüfungs-Fehlern angezeigt werden.
                </para></listitem>

                <listitem><para>
                    <methodname>setErrorMessages(array $messages)</methodname>: Fügt mehrere
                    Fehlermeldungen hinzu die bei Form-Überprüfungs-Fehlern angezeigt werden, und
                    überschreibt alle vorher gesetzten Fehlermeldungen.
                </para></listitem>

                <listitem><para>
                    <methodname>getErrorMessages()</methodname>: Empfängt eine Liste von
                    selbstdefinierten Fehlermeldungen die vorher definiert wurden.
                </para></listitem>

                <listitem><para>
                    <methodname>clearErrorMessages()</methodname>: Entfernt alle eigenen
                    Fehlermeldungen die vorher definiert wurden.
                </para></listitem>

                <listitem><para>
                    <methodname>markAsError()</methodname>: Markiert das Element wie wenn die
                    Überprüfung fehlgeschlagen wäre.
                </para></listitem>

                <listitem><para>
                    <methodname>addError($message)</methodname>: Fügt einen Fehler zum eigenen
                    Stack der Fehlermeldungen hinzu und markiert das Element als ungültig.
                </para></listitem>

                <listitem><para>
                    <methodname>addErrors(array $messages)</methodname>: Fügt mehrere Nachrichten
                    zum eigenen Stack der Fehlermeldungen hinzu und markiert das Element als
                    ungültig.
                </para></listitem>

                <listitem><para>
                    <methodname>setErrors(array $messages)</methodname>: Überschreibt den eigenen
                    Stack der Fehlermeldungen mit den angegebenen Meldungen und markiert das Element
                    als ungültig.
                </para></listitem>
            </itemizedlist>

            <para>
                Alle auf diesem Weg gesetzten Fehler können übersetzt werden.
            </para>
        </sect3>

        <sect3 id="zend.form.forms.validation.values">
            <title>Nur einen gültigen Wert empfangen</title>

            <para>
                Es gibt Szenarien in denen man dem Benutzer erlauben will in verschiedenen Schritten
                mit einem gültigen Formular zu arbeiten. In der Zwischenzeit wird dem Benutzer
                erlaubt das Formular mit jedem Set an Werte zu speichern. Dann, wenn alle Daten
                spezifiziert wurden kann das Modell von der Building oder Prototyping Stufe zu einer
                Gültigen Stufe transferiert werden.
            </para>

            <para>
                Alle gültigen Werte die mit den übermittelten Daten übereinstimmen können empfangen
                werden indem folgendes aufgerufen wird:
            </para>

            <programlisting language="php"><![CDATA[
$validValues = $form->getValidValues($_POST);
]]></programlisting>
        </sect3>
    </sect2>

    <sect2 id="zend.form.forms.methods">
        <title>Methoden</title>

        <para>
            Nachfolgend ist eine komplette Liste der in <classname>Zend_Form</classname> vorhandenen
            Methoden, gruppiert nach Typ:
        </para>

        <itemizedlist>
            <listitem><para>Konfiguration und Optionen:</para>
                <itemizedlist>
                    <listitem>
                        <para><methodname>setOptions(array $options)</methodname></para>
                    </listitem>

                    <listitem>
                        <para><methodname>setConfig(Zend_Config $config)</methodname></para>
                    </listitem>
                </itemizedlist>
            </listitem>

            <listitem><para>Plugin Loader und Pfade:</para>
                <itemizedlist>
                    <listitem>
                        <para>
                            <code>setPluginLoader(Zend_Loader_PluginLoader_Interface $loader, $type
                            = null)</code>
                        </para>
                    </listitem>

                    <listitem>
                        <para><methodname>getPluginLoader($type = null)</methodname></para>
                    </listitem>

                    <listitem>
                        <para>
                            <methodname>addPrefixPath($prefix, $path, $type = null) </methodname>
                        </para>
                    </listitem>

                    <listitem>
                        <para><methodname>addPrefixPaths(array $spec)</methodname></para>
                    </listitem>

                    <listitem>
                        <para>
                            <methodname>addElementPrefixPath($prefix, $path, $type =
                                null)</methodname>
                        </para>
                    </listitem>

                    <listitem>
                        <para><methodname>addElementPrefixPaths(array $spec)</methodname></para>
                    </listitem>

                    <listitem>
                        <para>
                            <methodname>addDisplayGroupPrefixPath($prefix, $path)</methodname>
                        </para>
                    </listitem>
                </itemizedlist>
            </listitem>

            <listitem><para>Metadaten:</para>
                <itemizedlist>
                    <listitem>
                        <para><methodname>setAttrib($key, $value)</methodname></para>
                    </listitem>

                    <listitem>
                        <para><methodname>addAttribs(array $attribs)</methodname></para>
                    </listitem>

                    <listitem>
                        <para><methodname>setAttribs(array $attribs)</methodname></para>
                    </listitem>

                    <listitem><para><methodname>getAttrib($key)</methodname></para></listitem>

                    <listitem><para><methodname>getAttribs()</methodname></para></listitem>

                    <listitem><para><methodname>removeAttrib($key)</methodname></para></listitem>

                    <listitem><para><methodname>clearAttribs()</methodname></para></listitem>

                    <listitem><para><methodname>setAction($action)</methodname></para></listitem>

                    <listitem><para><methodname>getAction()</methodname></para></listitem>

                    <listitem><para><methodname>setMethod($method)</methodname></para></listitem>

                    <listitem><para><methodname>getMethod()</methodname></para></listitem>

                    <listitem><para><methodname>setName($name)</methodname></para></listitem>

                    <listitem><para><methodname>getName()</methodname></para></listitem>
                </itemizedlist>
            </listitem>

            <listitem><para>Elemente:</para>
                <itemizedlist>
                    <listitem>
                        <para>
                            <methodname>addElement($element, $name = null, $options =
                                null)</methodname>
                        </para>
                    </listitem>

                    <listitem>
                        <para><methodname>addElements(array $elements)</methodname></para>
                    </listitem>

                    <listitem>
                        <para><methodname>setElements(array $elements)</methodname></para>
                    </listitem>

                    <listitem><para><methodname>getElement($name)</methodname></para></listitem>

                    <listitem><para><methodname>getElements()</methodname></para></listitem>

                    <listitem><para><methodname>removeElement($name)</methodname></para></listitem>

                    <listitem><para><methodname>clearElements()</methodname></para></listitem>

                    <listitem>
                        <para><methodname>setDefaults(array $defaults)</methodname></para>
                    </listitem>

                    <listitem>
                        <para><methodname>setDefault($name, $value)</methodname></para>
                    </listitem>

                    <listitem><para><methodname>getValue($name)</methodname></para></listitem>

                    <listitem><para><methodname>getValues()</methodname></para></listitem>

                    <listitem>
                        <para><methodname>getUnfilteredValue($name)</methodname></para>
                    </listitem>

                    <listitem><para><methodname>getUnfilteredValues()</methodname></para></listitem>

                    <listitem>
                        <para><methodname>setElementFilters(array $filters)</methodname></para>
                    </listitem>

                    <listitem>
                        <para>
                            <methodname>setElementDecorators(array $decorators)</methodname>
                        </para>
                    </listitem>
                </itemizedlist>
            </listitem>

            <listitem><para>Subformen:</para>
                <itemizedlist>
                    <listitem>
                        <para>
                            <methodname>addSubForm(Zend_Form $form, $name, $order =
                                null)</methodname>
                        </para>
                    </listitem>

                    <listitem>
                        <para><methodname>addSubForms(array $subForms)</methodname></para>
                    </listitem>

                    <listitem>
                        <para><methodname>setSubForms(array $subForms)</methodname></para>
                    </listitem>

                    <listitem><para><methodname>getSubForm($name)</methodname></para></listitem>

                    <listitem><para><methodname>getSubForms()</methodname></para></listitem>

                    <listitem><para><methodname>removeSubForm($name)</methodname></para></listitem>

                    <listitem><para><methodname>clearSubForms()</methodname></para></listitem>

                    <listitem>
                        <para>
                            <methodname>setSubFormDecorators(array $decorators)</methodname>
                        </para>
                    </listitem>
                </itemizedlist>
            </listitem>

            <listitem><para>Anzeigegruppen:</para>
                <itemizedlist>
                    <listitem>
                        <para>
                            <methodname>addDisplayGroup(array $elements, $name, $options =
                                 null)</methodname>
                        </para>
                    </listitem>

                    <listitem>
                        <para><methodname>addDisplayGroups(array $groups)</methodname></para>
                    </listitem>

                    <listitem>
                        <para><methodname>setDisplayGroups(array $groups)</methodname></para>
                    </listitem>

                    <listitem>
                        <para><methodname>getDisplayGroup($name)</methodname></para>
                    </listitem>

                    <listitem><para><methodname>getDisplayGroups()</methodname></para></listitem>

                    <listitem>
                        <para><methodname>removeDisplayGroup($name)</methodname></para>
                    </listitem>

                    <listitem><para><methodname>clearDisplayGroups()</methodname></para></listitem>

                    <listitem>
                        <para>
                            <methodname>setDisplayGroupDecorators(array $decorators)</methodname>
                        </para>
                    </listitem>
                </itemizedlist>
            </listitem>

            <listitem><para>Prüfungen</para>
                <itemizedlist>
                    <listitem>
                        <para><methodname>populate(array $values)</methodname></para>
                    </listitem>

                    <listitem><para><methodname>isValid(array $data)</methodname></para></listitem>

                    <listitem>
                        <para><methodname>isValidPartial(array $data)</methodname></para>
                    </listitem>

                    <listitem>
                        <para><methodname>processAjax(array $data)</methodname></para>
                    </listitem>

                    <listitem><para><methodname>persistData()</methodname></para></listitem>

                    <listitem>
                        <para><methodname>getErrors($name = null)</methodname></para>
                    </listitem>

                    <listitem>
                        <para><methodname>getMessages($name = null)</methodname></para>
                    </listitem>
                </itemizedlist>
            </listitem>

            <listitem><para>Darstellung:</para>
                <itemizedlist>
                    <listitem>
                        <para>
                            <methodname>setView(Zend_View_Interface $view = null)</methodname>
                        </para>
                    </listitem>

                    <listitem><para><methodname>getView()</methodname></para></listitem>

                    <listitem>
                        <para>
                            <methodname>addDecorator($decorator, $options = null)</methodname>
                        </para>
                    </listitem>

                    <listitem>
                        <para><methodname>addDecorators(array $decorators)</methodname></para>
                    </listitem>

                    <listitem>
                        <para><methodname>setDecorators(array $decorators)</methodname></para>
                    </listitem>

                    <listitem><para><methodname>getDecorator($name)</methodname></para></listitem>

                    <listitem><para><methodname>getDecorators()</methodname></para></listitem>

                    <listitem>
                        <para><methodname>removeDecorator($name)</methodname></para>
                    </listitem>

                    <listitem><para><methodname>clearDecorators()</methodname></para></listitem>

                    <listitem>
                        <para>
                            <methodname>render(Zend_View_Interface $view = null)</methodname>
                        </para>
                    </listitem>
                </itemizedlist>
            </listitem>

            <listitem><para>I18n:</para>
                <itemizedlist>
                    <listitem>
                        <para>
                            <methodname>setTranslator(Zend_Translate_Adapter $translator =
                                null)</methodname>
                        </para>
                    </listitem>

                    <listitem><para><methodname>getTranslator()</methodname></para></listitem>

                    <listitem>
                        <para><methodname>setDisableTranslator($flag)</methodname></para>
                    </listitem>

                    <listitem>
                        <para><methodname>translatorIsDisabled()</methodname></para>
                    </listitem>
                </itemizedlist>
            </listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.form.forms.config">
        <title>Konfiguration</title>

        <para>
            <classname>Zend_Form</classname> ist über <methodname>setOptions()</methodname> und
            <methodname>setConfig()</methodname> vollständig konfigurierbar (oder durch die Übergabe
            von Optionen oder einem <classname>Zend_Config</classname> Objekt an den Konstruktor).
            Durch Verwendung dieser Methoden können Form Elemente, Anzeigegruppen, Dekoratore, und
            Metadaten spezifiziert werden.
        </para>

        <para>
            Als generelle Regel, wenn 'set' + der Optionsschlüssel zu einer
            <classname>Zend_Form</classname> Methode referieren, wird der angebotene Wert zu dieser
            Methode übergeben. Wenn die Methode nicht existiert, wird angenommen das der Schlüssel
            eine Referenz zu einem Attribut ist, und wird an <methodname>setAttrib()</methodname>
            übergeben.
        </para>

        <para>
            Ausnahmen zu dieser Regel sind die folgenden:
        </para>

        <itemizedlist>
            <listitem><para>
                    <code>prefixPaths</code> wird übergeben an
                    <methodname>addPrefixPaths()</methodname>
            </para></listitem>

            <listitem><para>
                <code>elementPrefixPaths</code> wird übergeben an
                <methodname>addElementPrefixPaths()</methodname>
            </para></listitem>

            <listitem><para>
                <code>displayGroupPrefixPaths</code> wird übergeben an
                <methodname>addDisplayGroupPrefixPaths()</methodname>
            </para></listitem>

            <listitem>
                <para>die folgenden Setter können nicht auf diesem Weg gesetzt werden:</para>

                <itemizedlist>
                    <listitem>
                        <para><code>setAttrib (da setAttribs *wird* funktionieren)</code></para>
                    </listitem>

                    <listitem><para><code>setConfig</code></para></listitem>

                    <listitem><para><code>setDefault</code></para></listitem>

                    <listitem><para><code>setOptions</code></para></listitem>

                    <listitem><para><code>setPluginLoader</code></para></listitem>

                    <listitem><para><code>setSubForms</code></para></listitem>

                    <listitem><para><code>setTranslator</code></para></listitem>

                    <listitem><para><code>setView</code></para></listitem>
                </itemizedlist>
            </listitem>
        </itemizedlist>

        <para>
            Als Beispiel ist hier eine Konfigurationsdatei die eine Konfiguration für jeden Typ
            von konfigurierbaren Daten übergibt:
        </para>

        <programlisting language="ini"><![CDATA[
[element]
name = "Registrierung"
action = "/user/register"
method = "post"
attribs.class = "zend_form"
attribs.onclick = "validate(this)"

disableTranslator = 0

prefixPath.element.prefix = "My_Element"
prefixPath.element.path = "My/Element/"
elementPrefixPath.validate.prefix = "My_Validate"
elementPrefixPath.validate.path = "My/Validate/"
displayGroupPrefixPath.prefix = "My_Group"
displayGroupPrefixPath.path = "My/Group/"

elements.username.type = "text"
elements.username.options.label = "Benutzername"
elements.username.options.validators.alpha.validator = "Alpha"
elements.username.options.filters.lcase = "StringToLower"
; natürlich mehr Elemente...

elementFilters.trim = "StringTrim"
;elementDecorators.trim = "StringTrim"

displayGroups.login.elements.username = "username"
displayGroups.login.elements.password = "password"
displayGroupDecorators.elements.decorator = "FormElements"
displayGroupDecorators.fieldset.decorator = "Fieldset"

decorators.elements.decorator = "FormElements"
decorators.fieldset.decorator = "FieldSet"
decorators.fieldset.decorator.options.class = "zend_form"
decorators.form.decorator = "Form"
]]></programlisting>

        <para>
            Das obige könnte einfach abstrahiert werden zu einer <acronym>XML</acronym> oder
            <acronym>PHP</acronym> Array-basierenden Konfigurations Datei.
        </para>
    </sect2>

    <sect2 id="zend.form.forms.custom">
        <title>Eigene Forms</title>

        <para>
            Eine Alternative zur Verwendung von Konfigurations-basierenden Forms ist es
            <classname>Zend_Form</classname> abzuleiten. Das hat einige Vorteile:
        </para>

        <itemizedlist>
            <listitem><para>
                Die Form kein einfachst mit Unittests getestet werden um sicherzugehen das
                Prüfungen und Darstellungen wie erwartet durchgeführt werden.
            </para></listitem>

            <listitem><para>
                Eine feinkörnige Kontrolle über individuelle Elemente.
            </para></listitem>

            <listitem><para>
                Wiederverwendung von Form Objekten, und größere Portierbarkeit (keine Notwendigkeit
                Konfigurationsdateien zu verfolgen).
            </para></listitem>

            <listitem><para>
                Eigene Funktionalitäten zu implementieren.
            </para></listitem>
        </itemizedlist>

        <para>
            Der typischste Anwendungsfall würde sein die <methodname>init()</methodname> Methode zu
            verwenden um spezielle Form Elemente und Konfigurationen zu definieren:
        </para>

        <programlisting language="php"><![CDATA[
class My_Form_Login extends Zend_Form
{
    public function init()
    {
        $username = new Zend_Form_Element_Text('username');
        $username->class = 'formtext';
        $username->setLabel('Benutzername:')
                 ->setDecorators(array(
                     array('ViewHelper',
                           array('helper' => 'formText')),
                     array('Label',
                           array('class' => 'label'))
                 ));

        $password = new Zend_Form_Element_Password('password');
        $password->class = 'formtext';
        $password->setLabel('Benutzername:')
                 ->setDecorators(array(
                     array('ViewHelper',
                           array('helper' => 'formPassword')),
                     array('Label',
                           array('class' => 'label'))
                 ));

        $submit = new Zend_Form_Element_Submit('login');
        $submit->class = 'formsubmit';
        $submit->setValue('Anmeldung')
               ->setDecorators(array(
                   array('ViewHelper',
                   array('helper' => 'formSubmit'))
               ));

        $this->addElements(array(
            $username,
            $password,
            $submit
        ));

        $this->setDecorators(array(
            'FormElements',
            'Fieldset',
            'Form'
        ));
    }
}
]]></programlisting>

        <para>
            Diese form kann instanziert werden mit einem einfachen:
        </para>

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

        <para>
            und die gesamte Funktionalität ist bereits eingestellt und bereit; keine
            Konfigurationsdateien notwendig. (Bitte beachten das dieses Beispiel sehr vereinfacht
            ist, da es keine Prüfungen oder Filter für die Elemente enthält.)
        </para>

        <para>
            Ein anderer üblicher Grund für die Erweiterung ist es ein Set von Standard Dekoratoren
            zu definieren. Das kann durch überladen der
            <methodname>loadDefaultDecorators()</methodname> Methode durchgeführt werden:
        </para>

        <programlisting language="php"><![CDATA[
class My_Form_Login extends Zend_Form
{
    public function loadDefaultDecorators()
    {
        $this->setDecorators(array(
            'FormElements',
            'Fieldset',
            'Form'
        ));
    }
}
]]></programlisting>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->