<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect1 id="zend.controller.actionhelpers" xmlns:xi="http://www.w3.org/2001/XInclude">
    <title>Action Helfer</title>

    <sect2 id="zend.controller.actionhelper.introduction">
        <title>Einführung</title>

        <para>
            Aktion Helfer erlauben Entwicklern Runtime und/oder On-Demand Funktionalität in jeden
            Aktion Controller zu inizieren der <classname>Zend_Controller_Action</classname>
            erweitert. Aktion Controller versuchen den Notwendigkeit zu minimieren, den abstrakten
            Aktion Controller zu erweitern um damit normale Aktion Controller Funktionen inizieren.
        </para>

        <para>
            Es gibt eine Menge an Wegen um Aktion Helfer zu verwenden. Aktion Helfer verwenden ein
            Broker System, ähnlich den Typen von Brokern in <link
                linkend="zend.view.helpers">Zend_View_Helper</link>, und denen von <link
                linkend="zend.controller.plugins">Zend_Controller_Plugin</link>. Aktion Helfer
            <classname>Zend_View_Helper</classname>) können bei Bedarf geladen und aufgerufen
            werden, oder Sie können wärend der Anfragezeit (Bootstrap) instanziert werden oder
            wären der Erstellungszeit des Aktion Controllers (<methodname>init()</methodname>). Um
            Sie näher zu verstehen, betrachten wir Ihre Verwendung in der folgenden Sektion.
        </para>
    </sect2>

    <sect2 id="zend.controller.actionhelper.initialization">
        <title>Helfer Initialisierung</title>

        <para>
            Ein Helfer kann auf vielen verschiedenen Wegen initialisiert werden, basierend auf den
            eigenen Bedürfnissen und den Funktionalitäten dieses Helfers.
        </para>

        <para>
            Ein Helfer Broker wir das der <varname>$_helper</varname> Teilnehmer von
            <classname>Zend_Controller_Action</classname> gespeichert; der Broker kann verwendet
            werden um Helfer zu empfangen oder aufzurufen. Einige Methoden das zu tun sind:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    Explizit <methodname>getHelper()</methodname> verwenden. Ihm einfach einen
                    Namen übergeben und ein Helfer Objekt wird zurückgegeben:
                </para>

                <programlisting language="php"><![CDATA[
$flashMessenger = $this->_helper->getHelper('FlashMessenger');
$flashMessenger->addMessage('Wir haben in der letzten Anfrage etwas getan');
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    Verwenden der <methodname>__get()</methodname> Funktionalität des Helfer
                    Brokers und Empfangen des Helfers wie wenn er eine Teilnehmer Eigenschaft des
                    Brokers wäre:
                </para>

                <programlisting language="php"><![CDATA[
$flashMessenger = $this->_helper->FlashMessenger;
$flashMessenger->addMessage('Wir haben in der letzten Anfrage etwas getan');
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    Letztendlich implmentieren die meisten Aktion Helfer die
                    <methodname>direct()</methodname> Methode welche eine spezielle,
                    Standardmethode im Helfer aufruft. In Beispiel des
                    <emphasis>FlashMessenger</emphasis>'s, wird
                    <methodname>addMessage()</methodname> aufgerufen:
                </para>

                <programlisting language="php"><![CDATA[
$this->_helper->FlashMessenger('Wir haben in der letzten Anfrage etwas getan');
]]></programlisting>
            </listitem>
        </itemizedlist>

        <note>
            <para>Alle oben angeführten Beispiel sind funktionell gleichwertig.</para>
        </note>

        <para>
            Man kann Helfer auch explizit instanzieren. Das kann gewollt sein wenn der Helfer
            ausserhalb eines Aktion Controllers verwendet werden soll, oder wenn ein Helfer an einen
            Helfer Broker übergeben wird um Ihn durch irgendeine Aktion zu verwenden. Instanziert
            wird er wie jede andere <acronym>PHP</acronym> Klasse.
        </para>
    </sect2>

    <sect2 id="zend.controller.actionhelper.broker">
        <title>Der Helfer Broker</title>

        <para>
            <classname>Zend_Controller_Action_HelperBroker</classname> behandelt die Details der
            Registrierung von Helfer Objekten und Helfer Pfaden, sowie dem Empfangen von Helfern bei
            Befarf.
        </para>

        <para>
            Um einen Helfer im Browser zu registrieren, kann <methodname>addHelper()</methodname>
            verwendet werden:
        </para>

        <programlisting language="php"><![CDATA[
Zend_Controller_Action_HelperBroker::addHelper($helper);
]]></programlisting>

        <para>
            Natürlich ist das Instanzieren und übergeben von Helfern an den Broker etwas Zeit- und
            Ressourcen intensiv, weswegen twei Methoden existieren um die Dinge etwas zu
            automatisieren: <methodname>addPrefix()</methodname> und
            <methodname>addPath()</methodname>.
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>addPrefix()</methodname> nimmt einen Klassenpräfix und verwendet
                    Ihn um einen Pfad zu ermitteln wo Helferklassen definiert wurden. Er nimmt an
                    das der Präfix den Konventionen der Benamung von Klassen im Zend Framework
                    folgt.
                </para>

                <programlisting language="php"><![CDATA[
// Helfer mit vorangestelltem My_Action_Helpers in My/Action/Helpers/ hinzufügen
Zend_Controller_Action_HelperBroker::addPrefix('My_Action_Helpers');
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    <methodname>addPath()</methodname> nimmt ein Verzeichnis als erstes Argument
                    und einen Klassenprefix als zweites Argument (Standardwert ist
                    '<classname>Zend_Controller_Action_Helper</classname>'). Das erlaubt es die
                    eigenen Klassenpräfixes mit speziellen Verzeichnissen zu verbinden.
                </para>

                <programlisting language="php"><![CDATA[
// Helfer mit vorangestelltem Helper in Plugins/Helpers/ hinzufügen
Zend_Controller_Action_HelperBroker::addPath('./Plugins/Helpers',
                                             'Helper');
]]></programlisting>
            </listitem>
        </itemizedlist>

        <para>
            Da diese Methoden statisch sind, können Sie zu jeder Zeit in der Controllerkette
            aufgerufen werden um Helfer dynamisch hinzuzufügen wenn es notwendig wird.
        </para>

        <para>
            Intern verwendet der Helfer Broker <link linkend="zend.loader.pluginloader">eine
            Instanz des PluginLoader's</link> um die Pfade zu verwalten. Man erhlt den PluginLoader
            indem die statische Methode <methodname>getPluginLoader()</methodname> verwendet, oder
            alternativ, eine eigene PluginLoader Instanz einfügt durch Verwenden von
            <methodname>setPluginLoader()</methodname>.
        </para>

        <para>
            Um zu ermitteln ob ein Helfer im Helfer Broker existiert, kann
            <methodname>hasHelper($name)</methodname> verwendet werden, wobei
            <varname>$name</varname> der Kurzname des Helfers ist (ohne das Präfix):
        </para>

        <programlisting language="php"><![CDATA[
// Prüft ob der 'redirector' Helfer im Broker registriert ist:
if (Zend_Controller_Action_HelperBroker::hasHelper('redirector')) {
    echo 'Der Redirector Helfer ist registriert';
}
]]></programlisting>

        <para>
            Es gibt auch zwei statische Methoden für das bekommen von Helfern vom Helferbroker:
            <methodname>getExistingHelper()</methodname> und
            <methodname>getStaticHelper()</methodname>.
            <methodname>getExistingHelper()</methodname> empfängt einen Helfer nur dann wenn er
            davor durch den Helferbroker ausgerufen wirde oder explizit in Ihm registriert wurde;
            wenn nicht wird eine Ausnahme geworfen. <methodname>getStaticHelper()</methodname>
            macht das selbe wie <methodname>getExistingHelper()</methodname>, wird aber versuchen
            den Helfer zu initiieren wenn dieser davor noch nicht im Helferstack registriert wurde.
            <methodname>getStaticHelper()</methodname> ist eine gute Wahl für das empfangen von
            Helfern welche man konfigurieren will.
        </para>

        <para>
            Beide Methoden nehmen ein einzelnes Argument, <varname>$name</varname>, welches der
            Kurzname des Helfers (ohne den Präfix) ist.
        </para>

        <programlisting language="php"><![CDATA[
// Prüfe ob der 'redirector' Helfer im Broker registriert ist und holt Ihn:
if (Zend_Controller_Action_HelperBroker::hasHelper('redirector')) {
    $redirector =
        Zend_Controller_Action_HelperBroker::getExistingHelper('redirector');
}

// Oder, Ihn einfach empfangen, ohne darüber nachzudenken ob er bereits
// registriert wurde oder nicht:
$redirector =
    Zend_Controller_Action_HelperBroker::getStaticHelper('redirector');
}
]]></programlisting>

        <para>
            Schlußendlich, um einen registrierten Helfer vom Broker zu entfernen, kann
            <methodname>removeHelper($name)</methodname> verwendet werden, wobei
            <varname>$name</varname> der Kurzname des Helfers ist (ohne den Prefix):
        </para>

        <programlisting language="php"><![CDATA[
// Wenn vorhanden, entferne den 'redirector' Helfer vom Broker:
if (Zend_Controller_Action_HelperBroker::hasHelper('redirector')) {
    Zend_Controller_Action_HelperBroker::removeHelper('redirector')
}
]]></programlisting>
    </sect2>

    <sect2 id="zend.controller.actionhelper.stockhelpers">
        <title>Eingebaute Aktions Helfer</title>

        <para>
            Zend Framework enthält standardmäßig verschiedene Action Helfer:
            <emphasis>AutoComplete</emphasis> für automatisierte Antworten für
            <acronym>AJAX</acronym> Autovervollständigung; <emphasis>ContextSwitch</emphasis> und
            <emphasis>AjaxContext</emphasis> für alternative Antwort Formate eigener Aktionen;
            einen <emphasis>FlashMessenger</emphasis> für die Behandlung von Kurznachrichten;
            <emphasis>Json</emphasis> für das verschlüsseln und senden von <acronym>JSON</acronym>
            Antworten; einen <emphasis>Redirector</emphasis>, um verschiedene Implementationen, für
            das Umleiten zu internen und externen Seiten, für die Anwendung bereitzustellen und
            einen <emphasis>ViewRenderer</emphasis> um den Prozess des Setzens eines View Objekts
            im Controller und dem Rendern von Views zu automatisieren.
        </para>

        <xi:include href="Zend_Controller-ActionHelpers-ActionStack.xml" />
        <xi:include href="Zend_Controller-ActionHelpers-AutoComplete.xml" />
        <xi:include href="Zend_Controller-ActionHelpers-ContextSwitch.xml" />
        <xi:include href="Zend_Controller-ActionHelpers-FlashMessenger.xml" />
        <xi:include href="Zend_Controller-ActionHelpers-Json.xml" />
        <xi:include href="Zend_Controller-ActionHelpers-Redirector.xml" />
        <xi:include href="Zend_Controller-ActionHelpers-ViewRenderer.xml" />
    </sect2>

    <sect2 id="zend.controller.actionhelper.writingyourown">
        <title>Schreiben eigener Helfer</title>

        <para>
            Aktions Helfer erweitern <classname>Zend_Controller_Action_Helper_Abstract</classname>,
            eine abstrakte Klasse die das Basisinterface bietet und vom Helfer Broker funktionell
            benötigt wird. Diese inkludiert die folgenden Methoden:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>setActionController()</methodname> wird verwendet um den aktuellen
                    Aktion Controller zu setzen.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>init()</methodname>, wird vom Helfer Broker wärend der
                    Instanzierung ausgeführt und kann verwendet werden um den Status zurückzusetzen
                    wenn mehrere Controller den gleichen Helfer in einer verketteten Aktion
                    verwenden.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>preDispatch()</methodname>, wird vor der ausführenden Aktion
                    gestartet.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>postDispatch()</methodname> wird ausgeführt nachdem eine Aktion
                    fertig ist -- selbst wenn ein <methodname>preDispatch()</methodname> Plugin die
                    Aktion abgebrochen hat. Normalerweise nützlich für das Saubermachen.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getRequest()</methodname> empfängt das aktuelle Anfrage Objekt.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getResponse()</methodname> empfängt das aktuelle Antwort Objekt.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getName()</methodname> empfängt den Helfernamen. Sie empfängt die
                    Portion des Klassennamens der dem letzten Unterstrich-Zeichen folgt, oder
                    andererseits den kompletten Klassennamen. Als Beispiel, wenn die Klasse
                    <classname>Zend_Controller_Action_Helper_Redirector</classname> heißt, wird
                    <emphasis>Redirector</emphasis> zurückgegeben; eine Klasse die
                    <emphasis>FooMessage</emphasis> heißt wird einfach sich selbst zurückgeben.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Optional kann eine <methodname>direct()</methodname> Methode in der eigenen Helfer
            Klasse inkludiert werden. Wenn Sie definiert ist, erlaubt Sie den Helfer als eine
            Methode des Helfer Brokers zu verwenden, um eine einfache rein-raus Verwendung des
            Helfers zu ermöglichen. Als Beispiel definiert der <link
                linkend="zend.controller.actionhelpers.redirector">Umleiter</link>
            <methodname>direct()</methodname> als einen Alias von <methodname>goto()</methodname>
            und erlaubt damit die Verwendung des Helfers wie folgt:
        </para>

        <programlisting language="php"><![CDATA[
// Umleiten zu /blog/view/item/id/42
$this->_helper->redirector('item', 'view', 'blog', array('id' => 42));
]]></programlisting>

        <para>
            Intern schaut die <methodname>__call()</methodname> Methode des Helfer Brokers nach
            einem Helfer der <emphasis>redirector</emphasis> heißt, prüft anschließend ob der
            Helfer eine definierte <methodname>direct()</methodname> Methode besitzt und ruft diese
            mit den angegebenen Argumenten auf.
        </para>

        <para>
            Wenn eine eigene Helfer Klasse erstellt wurde, kann man zu Ihr wie im obigen Kapitel
            beschrieben, Zugang erhalten.
        </para>
    </sect2>
</sect1>