<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect1 id="zend.form.decorators">
    <title>Erstellen von eigenem Form Markup durch Zend_Form_Decorator</title>

    <para>
        Die Darstellung eines Form Objektes ist komplett optional --
        <classname>Zend_Form</classname>'s render() Methoden müssen nicht einmal verwendet werden.
        Wenn es trotzdem so gemacht wird, dann werden Dekoratoren verwendet, um die verschiedenen
        Form Objekte darzustellen.
    </para>

    <para>
        Eine Vielzahl an Dekoratoren kann jedem Teil angefügt werden (Elemente, Anzeigegruppen,
        Unterformulare, oder das Form Objekt selbst); trotzdem kann nur ein Dekorator eines
        bestimmten Typs jedem Teil engefügt werden. Dekoratoren werden in der Reihenfolge aufgerufen
        in der sie registriert werden. Abhängig vom Dekorator, kann dieser den Inhalt ersetzen, der
        Ihm übergeben wurde, oder Inhalt anhängen oder voranstellen.
    </para>

    <para>
        Der Objektstatus wird durch Konfigurationsoptionen gesetzt die dem Konstruktor oder der
        <methodname>setOptions()</methodname> Methode des Dekorators übergeben werden. Wenn
        Dekoratoren, über <methodname>addDecorator()</methodname> oder ähnliche Methoden erstellt
        werden, können der Methode Optionen als Argument übergeben werden. Diese können verwendet
        werden um eine Platzierung zu spezifizieren, einen Separator festzulegen, der zwischen
        übergebenem Inhalt und neu erstelltem Inhalt verwendet wird, oder welche Option der
        Dekorator sonst noch unterstützt.
    </para>

    <para>
        Bevor jede <methodname>render()</methodname> Methode der Dekoratoren aufgerufen wird, wird
        das aktuelle Element im Dekorator mit <methodname>setElement()</methodname> gesetzt, was
        dem Dekorator zeigt welches Element dargestellt werden soll. Das erlaubt es Dekoratoren zu
        erstellen, die nur spezielle Abschnitte eines Elements darstellen -- wie das Label, den
        Wert, Fehlermeldungen, usw. Durch die Verbindung von verschiedenen Dekoratoren, die ein
        spezielles Segment des Elements darstellen, kann ein komplexes Markup gebaut werden, das
        das komplette Element repräsentiert.
    </para>

    <sect2 id="zend.form.decorators.operation">
        <title>Operationen</title>

        <para>
            Um einen Dekorator zu konfigurieren, kann ein Array von Optionen, oder ein
            <classname>Zend_Config</classname> Objekt an dessen Konstruktor übergeben werden, ein
            Array an <methodname>setOptions()</methodname>, oder ein
            <classname>Zend_Config</classname> Objekt an <methodname>setConfig()</methodname>.
        </para>

        <para>
            Die Standard Optionen beinhalten:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <property>placement</property>: Die Platzierung kann entweder 'append' oder
                    'prepend' sein (unabhängig von der Schreibweise), und definiert ob der Inhalt
                    der <methodname>render()</methodname> übergeben wird, angehängt oder
                    vorangestellt wird. Im Fall das ein Dekorator den Inhalt ersetzt wird diese
                    Einstellung ignoriert. Der Standardwert ist anhängen (append).
                </para>
            </listitem>

            <listitem>
                <para>
                    <property>separator</property>: Der Separator wird zwischen dem Inhalt der an
                    <methodname>render()</methodname> übergeben wird und durch den Dekorator neu
                    erstelltem Inhalt verwendet, oder zwischen Teilen die durch den Dekorator
                    dargestellt werden (z.B. FormElements verwenden Separatoren zwischen jedem
                    dargestellten Element). Im Fall das ein Dekorator den Inhalt ersetzt, wird
                    diese Einstellung ignoriert. Der Standardwert ist <constant>PHP_EOL</constant>.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Das Dekorator Interface spezifiziert Methoden für die Interaktion mit Optionen. Diese
            beinhalten:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>setOption($key, $value)</methodname>: Setzt eine einzelne Option.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getOption($key)</methodname>: Einen einzelnen Optionswert erhalten.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getOptions()</methodname>: Alle Optionen erhalten.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>removeOption($key)</methodname>: Eine einzelne Option entfernen.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>clearOptions()</methodname>: Alle Optionen entfernen.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Dekoratoren sollen mit den verschiedenen <classname>Zend_Form</classname> Klassentypen
            interagieren: <classname>Zend_Form</classname>,
            <classname>Zend_Form_Element</classname>,
            <classname>Zend_Form_DisplayGroup</classname>, und allen von ihnen abgeleiteten
            Klassen. Die Methode <methodname>setElement()</methodname> erlaubt es, das Objekt des
            Dekorators, mit den aktuell gearbeitet wird, zu setzen und
            <methodname>getElement()</methodname> wird verwendet um es zu Empfangen.
        </para>

        <para>
            Die <methodname>render()</methodname> Methode jedes Dekorators akzeptiert einen String
            <varname>$content</varname>. Wenn der erste Dekorator aufgerufen wird, ist dieser String
            typischerweise leer, während er bei nachfolgenden Aufrufen bekannt sein wird. Basierend
            auf dem Typ des Dekorators und den ihm übergebenen Optionen, wird der Dekorator
            entweder diesen String ersetzen, voranstellen oder anfügen; ein optionaler Separator
            wird in den späteren zwei Situationen verwendet.
        </para>
    </sect2>

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

        <para>
            <classname>Zend_Form</classname> wird mit vielen Standard Dekoratoren ausgeliefert;
            siehe <link linkend="zend.form.standardDecorators">das Kapitel über
                Standard Dekoratoren</link> für Details.
        </para>
    </sect2>

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

        <para>
            Wenn man der Meinung ist, dass die Notwendigkeiten der Darstellung sehr komplex sind,
            oder starke Anpassungen benötigt, sollte man sich überlegen einen eigenen Dekorator
            zu erstellen.
        </para>

        <para>
            Dekoratoren implementieren nur <classname>Zend_Form_Decorator_Interface</classname>.
            Das Interface spezifiziert folgendes:
        </para>

        <programlisting language="php"><![CDATA[
interface Zend_Form_Decorator_Interface
{
    public function __construct($options = null);
    public function setElement($element);
    public function getElement();
    public function setOptions(array $options);
    public function setConfig(Zend_Config $config);
    public function setOption($key, $value);
    public function getOption($key);
    public function getOptions();
    public function removeOption($key);
    public function clearOptions();
    public function render($content);
}
]]></programlisting>

        <para>
            Um es sich einfacher zu machen, kann man
            <classname>Zend_Form_Decorator_Abstract</classname> erweitern, welches alle Methoden
            ausser <methodname>render()</methodname> implementiert.
        </para>

        <para>
            Als Beispiel nehmen wir an, dass wir die Anzahl an verwendeten Dekoratoren verringern
            wollen, und einen "gemeinsamen" Dekorator erstellen der die Darstellung von Label,
            Element, jeglicher Fehlermeldungen, und Beschreibung in einem <acronym>HTML</acronym>
            'div' übernimmt. So ein 'gemeinsamer' Dekorator kann wie folgt erstellt werden:
        </para>

        <programlisting language="php"><![CDATA[
class My_Decorator_Composite extends Zend_Form_Decorator_Abstract
{
    public function buildLabel()
    {
        $element = $this->getElement();
        $label = $element->getLabel();
        if ($translator = $element->getTranslator()) {
            $label = $translator->translate($label);
        }
        if ($element->isRequired()) {
            $label .= '*';
        }
        $label .= ':';
        return $element->getView()
                       ->formLabel($element->getName(), $label);
    }

    public function buildInput()
    {
        $element = $this->getElement();
        $helper  = $element->helper;
        return $element->getView()->$helper(
            $element->getName(),
            $element->getValue(),
            $element->getAttribs(),
            $element->options
        );
    }

    public function buildErrors()
    {
        $element  = $this->getElement();
        $messages = $element->getMessages();
        if (empty($messages)) {
            return '';
        }
        return '<div class="errors">' .
               $element->getView()->formErrors($messages) . '</div>';
    }

    public function buildDescription()
    {
        $element = $this->getElement();
        $desc    = $element->getDescription();
        if (empty($desc)) {
            return '';
        }
        return '<div class="description">' . $desc . '</div>';
    }

    public function render($content)
    {
        $element = $this->getElement();
        if (!$element instanceof Zend_Form_Element) {
            return $content;
        }
        if (null === $element->getView()) {
            return $content;
        }

        $separator = $this->getSeparator();
        $placement = $this->getPlacement();
        $label     = $this->buildLabel();
        $input     = $this->buildInput();
        $errors    = $this->buildErrors();
        $desc      = $this->buildDescription();

        $output = '<div class="form element">'
                . $label
                . $input
                . $errors
                . $desc
                . '</div>'

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

        <para>
            Danach kannst du ihn in den Dekoratoren Pfad platzieren:
        </para>

        <programlisting language="php"><![CDATA[
// für ein Element:
$element->addPrefixPath('My_Decorator',
                        'My/Decorator/',
                        'decorator');

// für alle Elemente:
$form->addElementPrefixPath('My_Decorator',
                            'My/Decorator/',
                            'decorator');
]]></programlisting>

        <para>
            Man kann dann diesen Dekorator als 'gemeinsam' spezifizieren und diesen an ein Element
            anfügen:
        </para>

        <programlisting language="php"><![CDATA[
// Überschreibe existierende Dekoratoren mit diesem einzelnen:
$element->setDecorators(array('Composite'));
]]></programlisting>

        <para>
            Während dieses Beispiel zeigt, wie ein Dekorator erstellt werden kann, der komplexe
            Ausgaben von verschiedenen Element-Eigenschaften darstellt, können auch Dekoratoren
            erstellt werden die einzelne Aspekte eines Elements handhaben; die 'Decorator' und
            'Label' Dekoratoren sind exzellente Beispiele dieser Praxis. Das erlaubt es Dekotatoren
            zu mischen und anzupassen, um komplexe Ausgaben zu erhalten -- und auch die Überladung
            von einzelnen Aspekten der Dekoration für die Anpassung an eigene Bedürfnisse.
        </para>

        <para>
            Wenn man, zum Beispiel, eine einfache Anzeige benötigt, welche die, während der
            Validierung aufgetretenen, Fehlermeldungen ignoriert und dafür eine eigene Fehlermeldung
            anzeigt, kann man sich einen eigenen 'Errors' Dekorator erstellen:
        </para>

        <programlisting language="php"><![CDATA[
class My_Decorator_Errors
{
    public function render($content = '')
    {
        $output = '<div class="errors">Der angegebene Wert war ungültig;
            bitte nochmals versuchen</div>';

        $placement = $this->getPlacement();
        $separator = $this->getSeparator();

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

        <para>
            In diesem speziellen Beispiel, weil das letzte Segment 'Errors' des Dekorators auf
            <classname>Zend_Form_Decorator_Errors</classname> passt, wird er
            <emphasis>statt</emphasis> diesem Dekorator dargestellt -- was bedeutet, dass kein
            Dekorator verändert werden muß um die Ausgabe anzupassen. Durch die Benennung des
            Dekorators nach dem bestehenden Standard Dekorator, kann die Dekoration verändert werden
            ohne, dass der Dekorator des Elements verändert werden muss.
        </para>
    </sect2>

    <sect2 id="zend.form.decorators.individual">
        <title>Darstellung individueller Dekoratoren</title>

        <para>
            Da Dekoratoren verschiedene Metadaten, eines Elements oder Formulars das sie darstellen,
            ansprechen, ist es oft nützlich zu bestimmten Zeiten nur einen individuellen Dekorator
            darzustellen. Erfreulicherweise ist dieses Feature über Methodenüberladung in jeder
            der grundsätzlichen Klassen der Formulartypen möglich (Formulare, Unterformulare,
            Anzeigegruppen, Elemente).
        </para>

        <para>
            Um das zu tun muss einfach <methodname>render[DecoratorName]()</methodname> aufgerufen
            werden, wobei "[DecoratorName]" der "Kurzname" des eigenen Dekorators ist; optional kann
            Inhalt eingefügt werden der dargestellt werden soll. Zum Beispiel:
        </para>

        <programlisting language="php"><![CDATA[
// Nur den Label Dekorator des Elements darstellen:
echo $element->renderLabel();

//Nur die Anzeigegruppe Fieldset mit Inhalt darstellen:
echo $group->renderFieldset('fieldset content');

// Nur das HTML Tag des Forumars mit Inhalt darstellen:
echo $form->renderHtmlTag('wrap this content');
]]></programlisting>

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

        <para>
            Das kann speziell dann nützlich sein, wenn ein Formular mit dem ViewScript Dekorator
            dargestellt wird; jedes Element kann seine angehängten Dekoratoren verwenden um Inhalte
            darzustellen, aber mit fein-abgestimmter Kontrolle.
        </para>
    </sect2>
</sect1>
