<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect1 id="zend.form.elements">
    <title>Erstellen von Form Elementen mit Hilfe von Zend_Form_Element</title>

    <para>
        Ein Formular ist aus Elementen gemacht, die typischerweise mit einer <acronym>HTML</acronym>
        Form Eingabe korrespondieren. <classname>Zend_Form_Element</classname> kapselt einzelne
        Formularelemente mit den folgenden Bereichen die erfüllt werden sollen:
    </para>

    <itemizedlist>
        <listitem>
            <para>
                Prüfung (ist der übertragene Wert gültig?)
            </para>

            <itemizedlist>
                <listitem>
                    <para>Fangen von Fehlercodes und Nachrichten von Prüfungen</para>
                </listitem>
            </itemizedlist>
        </listitem>

        <listitem>
            <para>
                Filtern (wie wird das Element in Anführungsstriche gesetzt oder normalisiert bevor
                die Prüfung stattfinden und/oder für die Ausgabe?)
            </para>
        </listitem>

        <listitem>
            <para>Darstellung (wie wird das Element angezeigt?)</para>
        </listitem>

        <listitem>
            <para>
                Metadaten und Attribute (welche Informationen qualifizieren das Element näher?)
            </para>
        </listitem>
    </itemizedlist>

    <para>
        Die Basisklasse, <classname>Zend_Form_Element</classname>, hat begründete Standardwerte für
        viele Fälle, aber es ist am besten die Klasse zu erweitern für oft verwendete speziell
        benötigte Elemente. Zusätzlich wird Zend Framework mit einer Anzahl an Standard
        <acronym>XHTML</acronym> Elementen ausgeliefert; über diese kann im
        <link linkend="zend.form.standardElements">Kapitel über Standard Elemente</link>
        nachgelesen werden.
    </para>

    <sect2 id="zend.form.elements.loaders">
        <title>Plugin Loader</title>

        <para>
            <classname>Zend_Form_Element</classname> verwendet
            <link linkend="zend.loader.pluginloader">Zend_Loader_PluginLoader</link> um es
            Entwicklern zu erlauben Orte für alternative Prüfungen, Filter und Dekoratoren zu
            definieren. Jeder hat seinen eigenen Plugin Loader assoziiert, und generelle
            Zugriffspunkte werden verwendet um jeden zu empfangen oder zu ändern.
        </para>

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

        <para>
            Die Methoden die für die Interaktion mit Plugin Loadern verwendet werden, sind die
            folgenden:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>setPluginLoader($loader, $type)</methodname>:
                    <varname>$loader</varname> ist das Plugin Loader Objekt selbst, während
                    <varname>$type</varname> eine der oben spezifizierten Typen ist. Das setzt den
                    Plugin Loader für den gegebenen Typ auf das neu spezifizierte Loader Objekt.
                </para>
            </listitem>

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

            <listitem>
                <para>
                    <methodname>addPrefixPath($prefix, $path, $type = null)</methodname>: Fügt eine
                    Präfix/Pfad Assoziation hinzu, Wenn <varname>$type</varname>
                    <constant>FALSE</constant> ist, wird versucht den Pfad zu allen Loadern
                    hinzuzufügen durch anhängen des Präfix von jedem "_Validate", "_Filter", und
                    "_Decorator"; und anhängen des Pfades an "Validate/", "Filter/", und
                    "Decorator/". Wenn alle extra Formular Elementklassen unter einer üblichen
                    Hirarchie stehen, ist das die bequemste Methode für das Setzen von
                    grundsätzlichen Präfixen.
                </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 Arrayelement ein Array mit den Sclüsseln 'path', 'prefix' und 'type' ist.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Eigene Prüfungen, Filter und Dekoratoren sind ein einfacher Weg um Funktionalität
            zwischen Forms zu teilen und eigene Funktionalitäten zu kapseln.
        </para>

        <example id="zend.form.elements.loaders.customLabel">
            <title>Eigenes Label</title>

            <para>
                Ein üblicher Verwendungszweck ist es Ersetzungen für Standardklassen anzubieten.
                Zum Beispiel wenn man eine andere Implementation des 'Label' Dekorators anbieten
                will -- zum Beispiel um immer einen Bindestrich anzufügen -- dann könnte man einen
                eigenen 'Label' Dekorator mit einem eigenen Klassenpräfix erstellen, und diesen
                zum eigenen Präfix Pfad hinzufügen.
            </para>

            <para>
                Beginnen wir mit einem eigenen Label Dekorator. Wir geben ihm den Klassenpräfix
                "My_Decorator", und die Klasse selbst wird in der Datei "My/Decorator/Label.php"
                sein.
            </para>

            <programlisting language="php"><![CDATA[
class My_Decorator_Label extends Zend_Form_Decorator_Abstract
{
    protected $_placement = 'PREPEND';

    public function render($content)
    {
        if (null === ($element = $this->getElement())) {
            return $content;
        }
        if (!method_exists($element, 'getLabel')) {
            return $content;
        }

        $label = $element->getLabel() . ':';

        if (null === ($view = $element->getView())) {
            return $this->renderLabel($content, $label);
        }

        $label = $view->formLabel($element->getName(), $label);

        return $this->renderLabel($content, $label);
    }

    public function renderLabel($content, $label)
    {
        $placement = $this->getPlacement();
        $separator = $this->getSeparator();

        switch ($placement) {
            case 'APPEND':
                return $content . $separator . $label;
            case 'PREPEND':
            default:
                return $label . $separator . $content;
        }
    }
}
]]></programlisting>

            <para>
                Jetzt kann dem Element mitgeteilt werden diesen Plugin Pfad zu verwenden wenn
                nach Dekoratoren gesucht wird:
            </para>

            <programlisting language="php"><![CDATA[
$element->addPrefixPath('My_Decorator', 'My/Decorator/', 'decorator');
]]></programlisting>

            <para>
                Alternativ kann das bei der Form gemacht werden um sicherzustellen das alle
                Dekoratore diesen Pfad verwenden:
            </para>

            <programlisting language="php"><![CDATA[
$form->addElementPrefixPath('My_Decorator', 'My/Decorator/', 'decorator');
]]></programlisting>

            <para>
                Wird dieser Pfad hinzugefügt, wenn ein Dekorator hinzugefügt wird, wird der
                Pfad 'My/Decorator/' zuerst durchsucht um zu sehen ob der Dekorator dort existiert.
                Als Ergebnis wird 'My_Decorator_Label' jetzt verwendet wenn der 'Labe' Dekorator
                angefragt wird.
            </para>
        </example>
    </sect2>

    <sect2 id="zend.form.elements.filters">
        <title>Filter</title>

        <para>
            Es ist oft nützlich und/oder notwendig einige Normalisierungen an Eingaben vorzunehmen,
            bevor diese geprüft werden - zum Beispiel kann es gewünscht sein alles an
            <acronym>HTML</acronym> zu entfernen, aber die Prüfungen auf dem verbleibenden
            durchzuführen um sicherzustellen, dass die Übertragung gültig ist. Oder man will
            Leerzeichen bei Eingaben entfernen, damit eine StringLength Prüfung kein falsches
            "Korrekt" zurückgibt. Diese Operationen können durchgeführt werden indem
            <classname>Zend_Filter</classname> verwendet wird, und
            <classname>Zend_Form_Element</classname> unterstützt Filterketten, was es erlaubt
            mehrere, sequentielle Filter zu spezifizieren und anzupassen. Das Filtern geschieht
            während der Prüfung und wenn der Wert des Elements über
            <methodname>getValue()</methodname> geholt wird:
        </para>

        <programlisting language="php"><![CDATA[
$filtered = $element->getValue();
]]></programlisting>

        <para>
            Filter können der Kette auf zwei Wegen hinzugefügt werden:
        </para>

        <itemizedlist>
            <listitem><para>Übergabe einer konkreten Filterinstanz</para></listitem>

            <listitem>
                <para>
                    Angabe eines kurzen Filternamens
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Sehen wir uns einige Beispiele an:
        </para>

        <programlisting language="php"><![CDATA[
// Konkrete Filterinstanz:
$element->addFilter(new Zend_Filter_Alnum());

// Kurzname des Filters:
$element->addFilter('Alnum');
$element->addFilter('alnum');
]]></programlisting>

        <para>
            Kurznamen sind typischerweise der Filtername ohne den Präfix. Im Standardfall bedeutet
            das keinen 'Zend_Filter_' Präfix. Zusätzlich muss der erste Buchstabe nicht
            großgeschrieben werden.
        </para>

        <note>
            <title>Eigene Filterklassen verwenden</title>

            <para>
                Wenn man sein eigenes Set an Filterklassen hat, kann man
                <classname>Zend_Form_Element</classname> mitteilen diese zu verwenden indem
                <methodname>addPrefixPath()</methodname> verwendet wird. Wenn man zum Beispiel
                eigene Filter unter dem 'My_Filter' Präfix hat, kann
                <classname>Zend_Form_Element</classname> dies auf dem folgenden Weg mitgeteilt
                werden:
            </para>

            <programlisting language="php"><![CDATA[
$element->addPrefixPath('My_Filter', 'My/Filter/', 'filter');
]]></programlisting>

            <para>
                (Beachten Sie, dass das dritte Agument indiziert welcher Plugin Loader auf welcher
                Aktion durchgeführt werden soll.)
            </para>
        </note>

        <para>
            Wenn man zu irgendeiner Zeit den ungefilterten Wert benötigt, kann die
            <methodname>getUnfilteredValue()</methodname> Methode verwendet werden:
        </para>

        <programlisting language="php"><![CDATA[
$unfiltered = $element->getUnfilteredValue();
]]></programlisting>

        <para>
            Für weitere Informationen über Filter, siehe die
            <link linkend="zend.filter.introduction">Dokumentation über Zend_Filter</link>.
        </para>

        <para>
            Die Methoden die mit Filtern assoziiert sind, beinhalten:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>addFilter($nameOfFilter, array $options = null)</methodname>
                </para>
            </listitem>

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

            <listitem>
                <para>
                    <methodname>setFilters(array $filters)</methodname> (Überschreibt alle Filter)
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getFilter($name)</methodname> (Empfängt ein Filterobjekt durch
                    seinen Namen)
                </para>
            </listitem>

            <listitem>
                <para><methodname>getFilters()</methodname> (Empfängt alle Filter)</para>
            </listitem>

            <listitem>
                <para>
                    <methodname>removeFilter($name)</methodname> (Entfernt einen Filter durch seinen
                    Namen)
                </para>
            </listitem>

            <listitem>
                <para><methodname>clearFilters()</methodname> (Entfernt alle Filter)</para>
            </listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.form.elements.validators">
        <title>Prüfungen</title>

        <para>
            Wenn man das Sicherheits-Mantra von "Eingabe filtern, Ausgabe escapen" unterschreibt
            dann wird man die Eingabe des Formulars prüfen ("Eingabefilterung") wollen. In
            <classname>Zend_Form</classname> enthält jedes Element seine eigene Prüfkette, die aus
            <classname>Zend_Validate_*</classname> Prüfungen besteht.
        </para>

        <para>
            Prüfungen können der Kette auf zwei Wegen hinzugefügt werden:
        </para>

        <itemizedlist>
            <listitem><para>Übergabe einer konkreten Prüfinstanz</para></listitem>

            <listitem>
                <para>
                    Anbieten eines kurzen Prüfnamens
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Einige Beispiele:
        </para>

        <programlisting language="php"><![CDATA[
// Konkrete Prüfinstanz:
$element->addValidator(new Zend_Validate_Alnum());

// Kurzer Prüfname:
$element->addValidator('Alnum');
$element->addValidator('alnum');
]]></programlisting>

        <para>
            Kurznamen sind typischerweise der Prüfname ohne den Präfix. Im Standardfall bedeutet
            das, keinen 'Zend_Validate_' Präfix. Zusätzlich muss der erste Buchstabe nicht
            großgeschrieben werden.
        </para>

        <note>
            <title>Eigene Prüfklassen verwenden</title>

            <para>
                Wenn man sein eigenes Set an Prüfklassen hat, kann man
                <classname>Zend_Form_Element</classname> mitteilen diese zu verwenden indem
                <methodname>addPrefixPath()</methodname> verwendet wird. Wenn man zum Beispiel
                eigene Prüfungen unter dem 'My_Validator' Präfix hat, kann
                <classname>Zend_Form_Element</classname> dies auf dem folgenden Weg mitgeteilt
                werden:
            </para>

            <programlisting language="php"><![CDATA[
$element->addPrefixPath('My_Validator', 'My/Validator/', 'validate');
]]></programlisting>

            <para>
                (Beachten Sie dass das dritte Agument zeigt welcher Plugin Loader auf welcher
                Aktion durchgeführt werden soll)
            </para>
        </note>

        <para>
            Wenn eine bestimmte Prüfung fehlschlägt, und die Ausführung von späteren Prüfungen
            verhindert werden soll, kann ein <constant>TRUE</constant> als zweiter Parameter
            übergeben werden:
        </para>

        <programlisting language="php"><![CDATA[
$element->addValidator('alnum', true);
]]></programlisting>

        <para>
            Wenn ein Stringname verwendet wird, um eine Prüfung hinzuzufügen und die Prüfklasse
            Argumente in ihrem Konstruktor akzeptiert, können diese als dritter Parameter an
            <methodname>addValidator()</methodname> als Array übergeben werden:
        </para>

        <programlisting language="php"><![CDATA[
$element->addValidator('StringLength', false, array(6, 20));
]]></programlisting>

        <para>
            Argumente die auf diesem Weg übergeben werden, sollten in der Reihenfolge sein in der
            sie im Konstruktor definiert sind. Das obige Beispiel instanziert die
            <classname>Zend_Validate_StringLenth</classname> Klasse mit den <varname>$min</varname>
            und <varname>$max</varname> Parametern:
        </para>

        <programlisting language="php"><![CDATA[
$validator = new Zend_Validate_StringLength(6, 20);
]]></programlisting>

        <note>
            <title>Eigene Fehlermeldungen für Prüfungen anbieten</title>

            <para>
                Einige Entwickler wollen eigene Fehlermeldungen für eine Prüfung anbieten.
                <methodname>Zend_Form_Element::addValidator()</methodname>'s
                <varname>$options</varname> Argument erlaubt es das zu tun, indem der Schlüssel
                'messages' angegeben wird und ein Array mit Schlüssel/Wert Paaren genutzt wird für
                das Setzen der Nachrichten Templates. Man muss die Fehlermeldungen der betreffenden
                Prüfung für die verschiedenen Fehlertypen von Prüfungen kennen.
            </para>

            <para>
                Eine bessere Option ist es <classname>Zend_Translate_Adapter</classname> in Formular
                zu verwenden. Fehlercodes werden automatisch dem Adapter durch den Standardmäßigen
                Fehlerdekorator übergeben; man kann durch die Erstellung von Übersetzungen
                eigene Fehlermeldungen für die verschiedenen Fehlercodes der Prüfung definieren.
            </para>
        </note>

        <para>
            Es können auch viele Prüfungen auf einmal gesetzt werden, indem
            <methodname>addValidators()</methodname> verwendet wird. Die grundsätzliche Verwendung
            ist es ein Array von Arrays zu übergeben, wobei jedes Array ein bis drei Werte enthält,
            die dem Konstruktor von <methodname>addValidator()</methodname> entsprechen:
        </para>

        <programlisting language="php"><![CDATA[
$element->addValidators(array(
    array('NotEmpty', true),
    array('alnum'),
    array('stringLength', false, array(6, 20)),
));
]]></programlisting>

        <para>
            Wenn man wortreicher oder expliziter sein will, dann können die Arrayschlüssel
            'validator', 'breakChainOnFailure', und 'options' verwendet werden:
        </para>

        <programlisting language="php"><![CDATA[
$element->addValidators(array(
    array(
        'validator'           => 'NotEmpty',
        'breakChainOnFailure' => true),
    array('validator' => 'alnum'),
    array(
        'validator' => 'stringLength',
        'options'   => array(6, 20)),
));
]]></programlisting>

        <para>
            Die Verwendung ist gut für die Illustration wie Prüfungen in einer Konfigurationsdatei
            definiert werden können:
        </para>

        <programlisting language="ini"><![CDATA[
element.validators.notempty.validator = "NotEmpty"
element.validators.notempty.breakChainOnFailure = true
element.validators.alnum.validator = "Alnum"
element.validators.strlen.validator = "StringLength"
element.validators.strlen.options.min = 6
element.validators.strlen.options.max = 20
]]></programlisting>

        <para>
            Es ist zu beachten, dass jedes Element einen Schlüssel hat, egal ob er benötigt wird
            oder nicht; das ist eine Einschränkung bei der Verwendung von Konfigurationsdateien --
            aber es macht auch klar, für was die Argumente stehen. Es ist einfach zu beachten das
            jede Prüfungsoption in der richtigen Reihenfolge spezifiziert werden muss.
        </para>

        <para>
            Um ein Element zu prüfen, muss der Wert an <methodname>isValid()</methodname> übergeben
            werden:
        </para>

        <programlisting language="php"><![CDATA[
if ($element->isValid($value)) {
    // gülig
} else {
    // ungültig
}
]]></programlisting>

        <note>
            <title>Die Prüfung findet an gefilterten Werte statt</title>

            <para>
                <methodname>Zend_Form_Element::isValid()</methodname> filtert Werte durch die
                angegebene Filterkette vor der Überprüfung. Siehe das
                <link linkend="zend.form.elements.filters">Kapitel über Filter</link> für
                weitere Informationen.
            </para>
        </note>

        <note>
            <title>Prüfungskontext</title>

            <para>
                <methodname>Zend_Form_Element::isValid()</methodname> unterstützt ein zusätzliches
                Argument <varname>$context</varname>. <methodname>Zend_Form::isValid()</methodname>
                übergibt ein komplettes Array von Daten die bearbeitet werden an
                <varname>$context</varname>, wenn ein Formular geprüft wird und
                <methodname>Zend_Form_Element::isValid()</methodname> übergibt es an jede Prüfung.
                Das bedeutet, dass man Prüfungen schreiben kann, die auf die Daten die an andere
                Formulare übergeben werden acht geben. Als Beispiel nehmen wir ein Anmeldeformular,
                welches die Felder für Passwort und Passwort Wiederholung hat; eine Prüfung würde
                sein, dass beide Felder den selben Wert beinhalten. So eine Prüfung könnte wie folgt
                aussehen:
            </para>

            <programlisting language="php"><![CDATA[
class My_Validate_PasswordConfirmation extends Zend_Validate_Abstract
{
    const NOT_MATCH = 'notMatch';

    protected $_messageTemplates = array(
        self::NOT_MATCH => 'Die Passwortüberprüfung war nicht erfolgreich'
    );

    public function isValid($value, $context = null)
    {
        $value = (string) $value;
        $this->_setValue($value);

        if (is_array($context)) {
            if (isset($context['password_confirm'])
                && ($value == $context['password_confirm']))
            {
                return true;
            }
        } elseif (is_string($context) && ($value == $context)) {
            return true;
        }

        $this->_error(self::NOT_MATCH);
        return false;
    }
}
]]></programlisting>
        </note>

        <para>
            Prüfungen werden in der Reihenfolge ausgeführt. Jede Prüfung wird ausgeführt solange bis
            eine Prüfung die mit einem <constant>TRUE</constant> Wert für
            <varname>$breakChainOnFailure</varname> bei Ihrer Prüfung fehlschlägt. Man sollte
            sichergehen, dass Prüfungen in einer begründeten Reihenfolge definiert werden.
        </para>

        <para>
            Nach einer fehlgeschlagenen Prüfung können Fehlercodes und Nachrichten von der
            Prüfkette empfangen werden:
        </para>

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

        <para>
            (Achtung: zurückgegebene Fehlermeldungen sind ein assoziatives Array von
            Fehlercode/Fehlermeldung Paaren.)
        </para>

        <para>
            Zusätzlich zu Prüfungen, kann spezifiziert werden, dass ein Element benötigt wird,
            indem <methodname>setRequired($flag)</methodname> verwendet wird. Standardmäßig ist
            dieses Flag <constant>FALSE</constant>. In Kombination mit
            <methodname>setAllowEmpty($flag)</methodname> (Standardmäßig <constant>TRUE</constant>)
            und <methodname>setAutoInsertNotEmptyValidator($flag)</methodname> (standardmäßig
            <constant>TRUE</constant>), kann das Verhalten der Prüfkette auf unterschiedliche Art
            und Weise verändert werden:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    Bei Verwendung der Standardwerte werden beim Prüfen eines Elements ohne der
                    Übergabe eines Werts, oder der Übergabe eines leeren Strings, alle Prüfungen
                    übersprungen und <constant>TRUE</constant> zurückgegeben.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>setAllowEmpty(false)</methodname> prüft, wenn die anderen zwei
                    erwähnten Flags unberührt bleiben, gegen die Prüfkette welche für dieses Element
                    definiert wurde, unabhängig von dem an <methodname>isValid()</methodname>
                    übergebenen Wert.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>setRequired(true)</methodname> fügt, wenn die anderen zwei
                    erwähnten Flags unberührt bleiben, eine 'NotEmpty' Prüfung an den Beginn der
                    Prüfkette (wenn nicht bereits eine gesetzt wurde) wobei das
                    <varname>$breakChainOnFailure</varname> Flag gesetzt wird. Das heißt, dass das
                    Flag folgende semantische Bedeutung bekommt: Wenn kein Wert übergeben wird, wird
                    die Übertragung sofort ungülig und der Benutzer wird informiert, was die anderen
                    Prüfungen davon abhält, ausgeführt zu werden, auf Daten, von denen wir bereits
                    wissen, dass sie ungültig sind.
                </para>

                <para>
                    Wenn dieses Verhalten nicht gewünscht ist kann es durch die Übergabe eines
                    <constant>FALSE</constant> Wert an
                    <methodname>setAutoInsertNotEmptyValidator($flag)</methodname> ausgeschaltet
                    werden; das verhindert, dass <methodname>isValid()</methodname> die 'NotEmpty'
                    Prüfung in der Prüfkette platziert.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Für weitere Informationen über Prüfungen kann in die
            <link linkend="zend.validate.introduction">Zend_Validate Dokumentation</link>
            gesehen werden.
        </para>

        <note>
            <title>Verwenden von Zend_Form_Elements als generell-eingesetzte Prüfung</title>

            <para>
                <classname>Zend_Form_Element</classname> implementiert
                <classname>Zend_Validate_Interface</classname> was bedeutet das ein Element auch als
                Prüfung füreinander verwendet werden kann, bezüglich nicht-Formular Prüfketten.
            </para>
        </note>

        <note>
            <title>Wann wird ein Element als leer erkannt?</title>

            <para>
                Wie erwähnt wird der 'NotEmpty' Prüfer verwendet um zu erkennen ob ein Element leer
                ist oder nicht. Aber <classname>Zend_Validate_NotEmpty</classname> arbeitet
                standardmäßig nicht wie <acronym>PHP</acronym>'s <methodname>empty()</methodname>
                Methode.
            </para>

            <para>
                Das bedeutet, wenn ein Element ein Integer <emphasis>0</emphasis> oder einen
                <emphasis>'0'</emphasis> String enthält dann wird dieses Element als nicht leer
                engesehen. Wenn man ein anderes Verhalten will, muss man seine eigene Instanz von
                <classname>Zend_Validate_NotEmpty</classname> erstellen. Dort kann man das Verhalten
                dieser Prüfung definieren. Siehe <ulink
                    url="zend.validate.set.notempty">Zend_Validate_NotEmpty</ulink> für Details.
            </para>
        </note>

        <para>
            Die mit der Prüfung assoziierten Methoden sind:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>setRequired($flag)</methodname> und
                    <methodname>isRequired()</methodname> erlauben es den Status des 'required'
                    Flag zu setzen und zu empfangen. Wenn der Wert auf <constant>TRUE</constant>
                    gesetzt wird, erzwingt dieses Flag, dass das Element, in den Daten die von
                    <classname>Zend_Form</classname> bearbeitet werden, vorhanden ist.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>setAllowEmpty($flag)</methodname> und
                    <methodname>getAllowEmpty()</methodname> erlauben es das Verhalten von
                    optionalen Elementen (z.B. Elementen in denen das 'required' Flag
                    <constant>FALSE</constant> ist) zu ändern. Wenn das 'allowEmpty' Flag
                    <constant>TRUE</constant> ist, werden leere Werte nicht an die Prüfkette
                    übergeben.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>setAutoInsertNotEmptyValidator($flag)</methodname> erlaubt es zu
                    definieren ob eine 'NotEmpty' Prüfung der Prüfkette vorangestellt wird wenn das
                    Element benötigt wird. Standardmäßig ist dieses Flag <constant>TRUE</constant>.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>addValidator($nameOrValidator, $breakChainOnFailure = false, array
                        $options = null)</methodname>
                </para>
            </listitem>

            <listitem>
                <para><methodname>addValidators(array $validators)</methodname></para>
            </listitem>

            <listitem>
                <para>
                    <methodname>setValidators(array $validators)</methodname> (Überschreibt alle
                    Prüfer)
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getValidator($name)</methodname> (Empfängt ein Prüfobjekt durch
                    seinen Namen)
                </para>
            </listitem>

            <listitem>
                <para><methodname>getValidators()</methodname> (Empfängt alle Prüfer)</para>
            </listitem>

            <listitem>
                <para>
                    <methodname>removeValidator($name)</methodname> (Entfernt einen Prüfer durch
                    seinen Namen)
                </para>
            </listitem>

            <listitem>
                <para><methodname>clearValidators()</methodname> (Entfernt alle Prüfer)</para>
            </listitem>
        </itemizedlist>

        <sect3 id="zend.form.elements.validators.errors">
            <title>Eigene Fehlermeldungen</title>

            <para>
                Von Zeit zu Zeit ist es gewünscht ein oder mehrere spezielle Fehlermeldungen zu
                spezifizieren, die statt der 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. Ab Version 1.6.0 des
                Zend Frameworks ist diese Funktionalität über die folgenden Methoden möglich.
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <methodname>addErrorMessage($message)</methodname>: Fügt eine Fehlermeldung
                        hinzu, die bei Formular-Ü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 Formular-Überprüfungs-Fehlern angezeigt
                        werden.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>setErrorMessages(array $messages)</methodname>: Fügt mehrere
                        Fehlermeldungen hinzu, die bei Formular-Ü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>hasErrors()</methodname>: Erkennt, ob ein Element eine
                        Überprüfung nicht bestanden hat oder, ob es als ungültig markiert wurde.
                    </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 Fehler die auf diesem Weg gesetzt werden, können übersetzt werden. Zusätzlich
                kann der Platzhalter "%value%" eingefügt werden um den Wert des Elements zu
                repräsentieren; dieser aktuelle Wert des Element wird eingefügt wenn die
                Fehlermeldung empfangen wird.
            </para>
        </sect3>
    </sect2>

    <sect2 id="zend.form.elements.decorators">
        <title>Dekoratoren</title>

        <para>
            Ein möglicher Schmerzpunkt für viele Webentwickler, ist die Erstellung von
            <acronym>XHTML</acronym> Formularen selbst. Für jedes Element muss der Entwickler das
            Markup für das Element selbst erstellen, typischerweise ein Label und, wenn sie nett zu
            den Benutzern sind, das Markup für die Anzeige von Fehlermeldungen von Prüfungen. Je
            mehr Elemente auf einer Seite sind, desto weniger trivial wird diese Aufgabe.
        </para>

        <para>
            <classname>Zend_Form_Element</classname> versucht dieses Problem durch die Verwendung
            von "Dekoratoren" zu lösen. Dekoratoren sind Klassen die Zugriff auf das Element
            haben und eine Methode zur Darstellung des Inhalts bieten. Für weitere Informationen
            darüber wie Dekoratoren arbeiten, kann im Kapitel über
            <link linkend="zend.form.decorators">Zend_Form_Decorator</link> eingesehen werden.
        </para>

        <para>
            Die von <classname>Zend_Form_Element</classname> verwendeten Standarddekoratoren sind:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis>ViewHelper</emphasis>: Spezifiziert einen View Helfer der verwendet
                    wird, um das Element darzustellen. Das 'helper' Attribut des Elements kann
                    verwendet werden, um zu spezifizieren welcher View Helfer verwendet werden soll.
                    Standardmäßig spezifiziert <classname>Zend_Form_Element</classname> den
                    'formText' View Helfer, aber individuelle Unterklassen spezifizieren
                    unterschiedliche Helfer.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>Errors</emphasis>: Fügt Fehlermeldungen an das Element an, indem es
                    <classname>Zend_View_Helper_FormErrors</classname> verwendet. Wenn keine
                    vorhanden sind, wird nichts hinzugefügt.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>Description</emphasis>: Fügt dem Element eine Beschreibung hinzu. Wenn
                    keine vorhanden ist, wird nichts angehängt. Standardmäßig wird die Beschreibung
                    in einem &lt;p&gt; Tag dargestellt mit einer CSS Klasse namens 'description'.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>HtmlTag</emphasis>: Umschliesst das Element und Fehler in einem
                    <acronym>HTML</acronym> &lt;dd&gt; Tag.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>Label</emphasis>: Stellt ein Label vor das Element, indem es
                    <classname>Zend_View_Helper_FormLabel</classname> verwendet, und umschliesst es
                    in einem &lt;dt&gt; Tag. Wenn kein Label angegeben wurde, wird nur das
                    &lt;dt&gt; Tag dargestellt.
                </para>
            </listitem>
        </itemizedlist>

        <note>
            <title>Standard Dekoratoren müssen nicht geladen werden</title>

            <para>
                Standardmäßig werden die Standarddekoratoren während der Initialisierung des Objekts
                geladen. Das kann durch die Übergabe der 'disableLoadDefaultDecorators' Option an
                den Konstruktor ausgeschaltet werden:
            </para>

            <programlisting language="php"><![CDATA[
$element = new Zend_Form_Element('foo',
                                 array('disableLoadDefaultDecorators' =>
                                     true)
                                );
]]></programlisting>

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

        <para>
            Da die Reihenfolge, in der die Dekoratoren registriert werden, von Bedeutung ist -- der
            zuerst registrierte Dekorator wird als erstes ausgeführt -- muss man sicherstellen, dass
            eigene Dekoratoren in der richtigen Reihenfolge registriert werden, oder sicherstellen,
            dass die Platzierungs-Optionen in einem ausgewogenen Weg gesetzt werden. Um ein Beispiel
            zu geben, ist hier ein Code der den Standarddekorator registriert:
        </para>

        <programlisting language="php"><![CDATA[
$this->addDecorators(array(
    array('ViewHelper'),
    array('Errors'),
    array('Description', array('tag' => 'p', 'class' => 'description')),
    array('HtmlTag', array('tag' => 'dd')),
    array('Label', array('tag' => 'dt')),
));
]]></programlisting>

        <para>
            Der anfängliche Inhalt wird vom 'ViewHelper' Dekorator erstellt, welche das Formular
            Element selbst erstellt. Als nächstes fängt der 'Errors' Dekorator Fehlermeldungen vom
            Element und, wenn welche vorhanden sind, übergibt er sie an den 'FormErrors' View Helfer
            zur Darstellung. Wenn eine Beschreibung vorhanden ist, wird der 'Description' Dekorator
            einen Paragraph der Klasse 'description' anhängen, der den beschreibenden Text für den
            betreffenden Inhalt enthält. Der nächste Dekorator, 'HtmlTag', umschliesst das Element
            und die Fehler in ein <acronym>HTML</acronym> &lt;dd&gt; Tag. Letztendlich, empfängt der
            letzte Dekorator, 'label' das Label des Elements und übergibt es an den 'FormLabel' View
            Helfer, und umschliesst es in einen <acronym>HTML</acronym> &lt;dt&gt; Tag; der Wert
            wird dem Inhalt standardmäßig vorangestellt. Die resultierende Ausgabe sieht
            grundsätzlich wie folgt aus:
        </para>

        <programlisting language="html"><![CDATA[
<dt><label for="foo" class="optional">Foo</label></dt>
<dd>
    <input type="text" name="foo" id="foo" value="123" />
    <ul class="errors">
        <li>"123" ist kein alphanumerischer Wert</li>
    </ul>
    <p class="description">
        Das ist etwas beschreibender Text betreffend dem Element.
    </p>
</dd>
]]></programlisting>

        <para>
            Für weitere Informationen über Dekoratoren gibt es das
            <link linkend="zend.form.decorators">Kapitel über Zend_Form_Decorator</link>.
        </para>

        <note>
            <title>Mehrere Dekoratoren des gleichen Typs verwenden</title>

            <para>
                Intern verwendet <classname>Zend_Form_Element</classname> eine Dekoratorklasse als
                Mechanismus für das Nachschauen wenn Dekoratore empfangen werden. Als Ergebnis,
                können mehrere Dekratoren nicht zur gleichen Zeit registriert werden; nachgeordnete
                Dekoratoren überschreiben jene, die vorher existiert haben.
            </para>

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

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

// Und es später erhalten:
$decorator = $element->getDecorator('FooBar');
]]></programlisting>

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

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

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

        <para>
            Die folgenden Methoden sind mit Dekoratoren assoziiert:
        </para>

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

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

            <listitem>
                <para>
                    <methodname>setDecorators(array $decorators)</methodname> (Überschreibt alle
                    Dekoratoren)
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getDecorator($name)</methodname> (Empfängt ein Dekoratorobjekt durch
                    seinen Namen)
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getDecorators()</methodname> (Empfängt alle Dekoratoren)
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>removeDecorator($name)</methodname> (Entfernt einen Dekorator durch
                    seinen Namen)
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>clearDecorators()</methodname> (Entfernt alle Dekoratoren)
                </para>
            </listitem>
        </itemizedlist>

        <para>
            <classname>Zend_Form_Element</classname> verwendet auch Überladung um die Darstellung
            von speziellen Dekoratoren zu erlauben. <methodname>__call()</methodname> interagiert
            mit Methoden auf mit dem Text 'render' anfangen und verwendet den Rest des
            Methodennamens dazu um nach einen Dekorator zu suchen; wenn er gefunden wird, wird er
            diesen <emphasis>einzelnen</emphasis> Dekorator darstellen. Jedes Argument das dem
            Methodenaufruf übergeben wird, wird als Inhalt für die Übergabe an die
            <methodname>render()</methodname> Methode des Dekorators verwendet. Als Beispiel:
        </para>

        <programlisting language="php"><![CDATA[
// Stellt nur den ViewHelper Dekorator dar:
echo $element->renderViewHelper();

// Nur den HtmlTag Dekorator darstellen, und Inhalt übergeben:
echo $element->renderHtmlTag("Das ist der Inhalt des HTML Tags");
]]></programlisting>

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

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

        <para>
            <classname>Zend_Form_Element</classname> behandelt eine Vielzahl von Attributen und
            Metadaten des Elements. Basisattribute sind:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis>name</emphasis>: Der Name des Elements. Verwendet die Zugriffsmethoden
                    <methodname>setName()</methodname> und <methodname>getName()</methodname>.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>label</emphasis>: Das Label des Elements. Verwendet die
                    Zugriffsmethoden <methodname>setLabel()</methodname> und
                    <methodname>getLabel()</methodname>.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>order</emphasis>: Der Index bei dem ein Element im Formular erscheinen
                    soll. Verwendet die Zugriffsmethoden <methodname>setOrder()</methodname> und
                    <methodname>getOrder()</methodname>.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>value</emphasis>: Der aktuelle Wert des Elements. Verwendet die
                    Zugriffsmethoden <methodname>setValue()</methodname> und
                    <methodname>getValue()</methodname>.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>description</emphasis>: Eine Beschreibung des Elements; wird oft
                    verwendet um Tooltips oder Javascript mäßige Hinweise anzubieten die den Zweck
                    des Elements beschreiben. Verwendet die Zugriffsmethoden
                    <methodname>setDescription()</methodname> und
                    <methodname>getDescription()</methodname>.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>required</emphasis>: Ein Flag, das anzeigt ob ein Element benötigt
                    wird wenn eine Prüfung des Formulars durchgeführt wird, oder nicht. Verwendet
                    die Zugriffsmethoden <methodname>setRequired()</methodname> und
                    <methodname>getRequired()</methodname>. Dieses Flag ist standardmäßig
                    <constant>FALSE</constant>.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>allowEmpty</emphasis>: Ein Flag, das indiziert ob ein nicht benötigtes
                    (optionales) Element versuchen soll leere Werte zu prüfen. Wenn es
                    <constant>TRUE</constant> ist, und das 'required' Flag
                    <constant>FALSE</constant>, dann werden leere Werte nicht an die Prüfkette
                    übergeben, und es wird <constant>TRUE</constant> angenommen. Verwendet die
                    Zugriffsmethoden <methodname>setAllowEmpty()</methodname> und
                    <methodname>getAllowEmpty()</methodname>. Dieses Flag ist standardmäßig
                    <constant>TRUE</constant>.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>autoInsertNotEmptyValidator</emphasis>: Ein Flag, das indiziert, ob
                    eine 'NotEmpty' Prüfung eingefügt werden soll, wenn das Element benötigt wird,
                    oder nicht. Standardmäßig ist dieses Flag <constant>TRUE</constant>. Das Flag
                    kann mit <methodname>setAutoInsertNotEmptyValidator($flag)</methodname> gesetzt
                    und der Wert mit <methodname>autoInsertNotEmptyValidator()</methodname>
                    ermittelt werden.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Formular Elemente können zusätzliche Metadaten benötigen. Für <acronym>XHTML</acronym>
            Form Elemente zum Beispiel, kann es gewünscht sein, Attribute wie die Klasse oder die Id
            zu spezifizieren. Für die Durchführung gibt es ein Set von Zugriffsmethoden:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis>setAttrib($name, $value)</emphasis>: Fügt ein Attribut hinzu
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>setAttribs(array $attribs)</emphasis>: Wie addAttribs(), aber
                    überschreibend
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>getAttrib($name)</emphasis>: Empfägt einen einzelnen Attributwert
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>getAttribs()</emphasis>: Empfängt alle Attribute als Schlüssel/Wert
                    Paare
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Die meiste Zeit kann auf sie, trotzdem, einfach als Objekteigenschaften zugegriffen
            werden, da <classname>Zend_Form_Element</classname> das Überladen realisiert und den
            Zugriff zu ihnen erlaubt:
        </para>

        <programlisting language="php"><![CDATA[
// Gleichbedeutend mit $element->setAttrib('class', 'text'):
$element->class = 'text;
]]></programlisting>

        <para>
            Standardmäßig werden alle Attribute, die an den View Helfer übergeben werden, auch vom
            Element während der Darstellung verwendet, und als <acronym>HTML</acronym> Attribute des
            Element Tags dargestellt.
        </para>
    </sect2>

    <sect2 id="zend.form.elements.standard">
        <title>Standard Elemente</title>

        <para>
            <classname>Zend_Form</classname> wird mit einer Anzahl an Standardelementen
            ausgeliefert; lesen Sie das Kapitel über
            <link linkend="zend.form.standardElements">Standard Elemente</link> für vollständige
            Details.
        </para>
    </sect2>

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

        <para>
            <classname>Zend_Form_Element</classname> hat viele, viele Methoden. Was folgt, ist eine
            kurze Zusammenfassung ihrer Signatur - 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>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>

            <listitem>
                <para>Eigenschaften:</para>

                <itemizedlist>
                    <listitem><para><methodname>setName($name)</methodname></para></listitem>
                    <listitem><para><methodname>getName()</methodname></para></listitem>
                    <listitem><para><methodname>setValue($value)</methodname></para></listitem>
                    <listitem><para><methodname>getValue()</methodname></para></listitem>
                    <listitem><para><methodname>getUnfilteredValue()</methodname></para></listitem>
                    <listitem><para><methodname>setLabel($label)</methodname></para></listitem>
                    <listitem><para><methodname>getLabel()</methodname></para></listitem>

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

                    <listitem><para><methodname>getDescription()</methodname></para></listitem>
                    <listitem><para><methodname>setOrder($order)</methodname></para></listitem>
                    <listitem><para><methodname>getOrder()</methodname></para></listitem>
                    <listitem><para><methodname>setRequired($flag)</methodname></para></listitem>
                    <listitem><para><methodname>getRequired()</methodname></para></listitem>
                    <listitem><para><methodname>setAllowEmpty($flag)</methodname></para></listitem>
                    <listitem><para><methodname>getAllowEmpty()</methodname></para></listitem>

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

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

                    <listitem><para><methodname>setIgnore($flag)</methodname></para></listitem>
                    <listitem><para><methodname>getIgnore()</methodname></para></listitem>
                    <listitem><para><methodname>getType()</methodname></para></listitem>

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

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

                    <listitem><para><methodname>getAttrib($name)</methodname></para></listitem>
                    <listitem><para><methodname>getAttribs()</methodname></para></listitem>
                </itemizedlist>
            </listitem>

            <listitem>
                <para>Plugin Loader und Pfade:</para>

                <itemizedlist>
                    <listitem>
                        <para>
                            <methodname>setPluginLoader(Zend_Loader_PluginLoader_Interface $loader,
                                $type)</methodname>
                        </para>
                    </listitem>

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

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

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

            <listitem>
                <para>Prüfung:</para>

                <itemizedlist>
                    <listitem>
                        <para>
                            <methodname>addValidator($validator, $breakChainOnFailure = false,
                                $options = array())</methodname>
                        </para>
                    </listitem>

                    <listitem>
                        <para><methodname>addValidators(array $validators)</methodname></para>
                    </listitem>

                    <listitem>
                        <para><methodname>setValidators(array $validators)</methodname></para>
                    </listitem>

                    <listitem><para><methodname>getValidator($name)</methodname></para></listitem>
                    <listitem><para><methodname>getValidators()</methodname></para></listitem>

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

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

                    <listitem>
                        <para><methodname>isValid($value, $context = null)</methodname></para>
                    </listitem>

                    <listitem><para><methodname>getErrors()</methodname></para></listitem>
                    <listitem><para><methodname>getMessages()</methodname></para></listitem>
                </itemizedlist>
            </listitem>

            <listitem>
                <para>Filter:</para>

                <itemizedlist>
                    <listitem>
                        <para>
                            <methodname>addFilter($filter, $options = array())</methodname>
                        </para>
                    </listitem>

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

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

                    <listitem><para><methodname>getFilter($name)</methodname></para></listitem>
                    <listitem><para><methodname>getFilters()</methodname></para></listitem>
                    <listitem><para><methodname>removeFilter($name)</methodname></para></listitem>
                    <listitem><para><methodname>clearFilters()</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>
        </itemizedlist>
    </sect2>

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

        <para>
            Der Konstruktor von <classname>Zend_Form_Element</classname> akzeptiert entweder einen
            Array von Optionen oder ein <classname>Zend_Config</classname> Objekt das Optionen
            enthält, und es kann auch durch Verwendung von <methodname>setOptions()</methodname>
            oder <methodname>setConfig()</methodname> konfiguriert werden. Generell, werden die
            Schlüssel wie folgt benannt:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    Wenn 'set' + Schlüssel auf eine <classname>Zend_Form_Element</classname> Methode
                    zeigt, dann wird der angebotene Wert zu dieser Methode übermittelt.
                </para>
            </listitem>

            <listitem>
                <para>Andernfalls wird der Wert verwendet um ein Attribut zu setzen.</para>
            </listitem>
        </itemizedlist>

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

        <itemizedlist>
            <listitem>
                <para>
                    <property>prefixPath</property> wird an
                    <methodname>addPrefixPaths()</methodname> übergeben
                </para>
            </listitem>

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

                <itemizedlist>
                    <listitem>
                        <para>
                                <property>setAttrib</property> (über <property>setAttribs</property>
                                <emphasis>wird</emphasis> es funktionieren)
                        </para>
                    </listitem>

                    <listitem><para><property>setConfig</property></para></listitem>
                    <listitem><para><property>setOptions</property></para></listitem>
                    <listitem><para><property>setPluginLoader</property></para></listitem>
                    <listitem><para><property>setTranslator</property></para></listitem>
                    <listitem><para><property>setView</property></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 = "foo"
value = "foobar"
label = "Foo:"
order = 10
required = true
allowEmpty = false
autoInsertNotEmptyValidator = true
description = "Foo Elemente sind für Beispiele"
ignore = false
attribs.id = "foo"
attribs.class = "element"
; Setzt das 'onclick' Attribut
onclick = "autoComplete(this, '/form/autocomplete/element')"
prefixPaths.decorator.prefix = "My_Decorator"
prefixPaths.decorator.path = "My/Decorator/"
disableTranslator = 0
validators.required.validator = "NotEmpty"
validators.required.breakChainOnFailure = true
validators.alpha.validator = "alpha"
validators.regex.validator = "regex"
validators.regex.options.pattern = "/^[A-F].*/$"
filters.ucase.filter = "StringToUpper"
decorators.element.decorator = "ViewHelper"
decorators.element.options.helper = "FormText"
decorators.label.decorator = "Label"
]]></programlisting>
    </sect2>

    <sect2 id="zend.form.elements.custom">
        <title>Eigene Elemente</title>

        <para>
            Es können eigene Elemente durch die Erweiterung der
            <classname>Zend_Form_Element</classname> Klasse erstellt werden. Übliche Gründe hierfür
            sind:
        </para>

        <itemizedlist>
            <listitem>
                <para>Elemente, die eine gemeinsame Prüfung und/oder Filter teilen</para>
            </listitem>

            <listitem>
                <para>Elemente die eine eigene Dekoratoren Funktionalität haben</para>
            </listitem>
        </itemizedlist>

        <para>
            Es gibt zwei Methoden die typischerweise verwendet werden, um ein Element zu erweitern:
            <methodname>init()</methodname>, was verwendet werden kannm um eine eigene
            Initialisierungs-Logik zum Element hinzuzufügen, und
            <methodname>loadDefaultDecorators()</methodname>, was verwendet werden kann um eine
            Liste von Standard Dekoratoren zu setzen, die vom Element verwendet werden sollen.
        </para>

        <para>
            Als Beispiel nehmen wir an, dass alle Text Elemente eines Formulars die erstellt werden
            mit <classname>StringTrim</classname> gefiltert werden müssen, mit einem gemeinsamen
            Regulären Ausdruck und das ein eigener Dekorator 'My_Decorator_TextItem' verwendet
            werden soll, der für die Darstellung von ihnen erstellt wurde; zusätzlich gibt es eine
            Anzahl an Standardattributen, wie 'size', 'maxLength', und 'class', die spezifiziert
            werden sollen. So ein Element könnte wie folgt definiert werden:
        </para>

        <programlisting language="php"><![CDATA[
class My_Element_Text extends Zend_Form_Element
{
    public function init()
    {
        $this->addPrefixPath('My_Decorator', 'My/Decorator/', 'decorator')
             ->addFilters('StringTrim')
             ->addValidator('Regex', false, array('/^[a-z0-9]{6,}$/i'))
             ->addDecorator('TextItem')
             ->setAttrib('size', 30)
             ->setAttrib('maxLength', 45)
             ->setAttrib('class', 'text');
    }
}
]]></programlisting>

        <para>
            Man könnte dann das Formular Objekt über den Präfix Pfad für diese Elemente informieren,
            und die Erstellung der Elemente beginnen:
        </para>

        <programlisting language="php"><![CDATA[
$form->addPrefixPath('My_Element', 'My/Element/', 'element')
     ->addElement('text', 'foo');
]]></programlisting>

        <para>
            Das 'foo' Element wird vom Typ <classname>My_Element_Text</classname> sein, und dem
            beschriebenen Verhalten entsprechen.
        </para>

        <para>
            Eine andere Methode, die man überschreiben sollte, wenn
            <classname>Zend_Form_Element</classname> erweitert wird, ist die
            <methodname>loadDefaultDecorators()</methodname> Methode. Diese Methode lädt fallweise
            ein Set von Standarddekoratoren für das Element; es kann gewünscht sein, eigene
            Dekoratoren in der erweiterten Klasse zu verwenden:
        </para>

        <programlisting language="php"><![CDATA[
class My_Element_Text extends Zend_Form_Element
{
    public function loadDefaultDecorators()
    {
        $this->addDecorator('ViewHelper')
             ->addDecorator('DisplayError')
             ->addDecorator('Label')
             ->addDecorator('HtmlTag',
                            array('tag' => 'div', 'class' => 'element'));
    }
}
]]></programlisting>

        <para>
            Es gibt viele Wege, Elemente anzupassen; man sollte sicherstellen die
            <acronym>API</acronym> Dokumentation von <classname>Zend_Form_Element</classname> zu
            lesen um alle vorhandenen Methoden zu kennen.
        </para>
    </sect2>
</sect1>