<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 15156 -->
<!-- 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 Kontroller zu inizieren der <classname>Zend_Controller_Action</classname>
            erweitert. Aktion Kontroller versuchen den Notwendigkeit zu minimieren, den abstrakten
            Aktion Kontroller zu erweitern um damit normale Aktion Kontroller 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 Kontrollers (init()). 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 <code>$_helper</code> 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 <code>getHelper()</code> verwenden. Ihm einfach einen Namen übergeben
                    und ein Helfer Objekt wird zurückgegeben:
                </para>

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

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

                <programlisting role="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 <code>direct()</code>
                    Methode welche eine spezielle, Standardmethode im Helfer aufruft. In Beispiel
                    des <code>FlashMessenger</code>s, wird <code>addMessage()</code> aufgerufen:
                </para>

                <programlisting role="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 Kontrollers 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 PHP 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 <code>addHelper</code> verwendet
            werden:
        </para>

        <programlisting role="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: <code>addPrefix()</code> und <code>addPath()</code>.
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>addPrefix()</code> nimmt einen Klassenprefix und verwendet Ihn um einen
                    Pfad zu ermitteln wo Helferklassen definiert wurden. Er nimmt an das der Prefix
                    den Konventionen der Benamung von Klassen im Zend Frameworks folgt.
                </para>

                <programlisting role="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>
                    <code>addPath()</code> nimmt ein Verzeichnis als erstes Argument und einen
                    Klassenprefix als zweites Argument (Standardwert ist
                    'Zend_Controller_Action_Helper'). Das erlaubt es die eigenen Klassenprefixes mit
                    speziellen Verzeichnissen zu verbinden.
                </para>

                <programlisting role="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 Kontrollerkette
            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 <code>getPluginLoader()</code> verwendet, oder alternativ, eine
            eigene PluginLoader Instanz einfügt durch Verwenden von <code>setPluginLoader()</code>.
        </para>

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

        <programlisting role="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:
            <code>getExistingHelper()</code> und <code>getStaticHelper()</code>.
            <code>getExistingHelper()</code> 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. <code>getStaticHelper()</code> macht das selbe wie
            <code>getExistingHelper()</code>, wird aber versuchen den Helfer zu initiieren wenn
            dieser davor noch nicht im Helferstack registriert wurde. <code>getStaticHelper()</code>
            ist eine gute Wahl für das empfangen von Helfern welche man konfigurieren will.
        </para>

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

        <programlisting role="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
            <code>removeHelper($name)</code> verwendet werden, wobei <code>$name</code> der Kurzname
            des Helfers ist (ohne den Prefix):
        </para>

        <programlisting role="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:
            <code>AutoComplete</code> für automatisierte Antworten für AJAX Autovervollständigung;
            <code>ContextSwitch</code> und <code>AjaxContext</code> für alternative Antwort Formate
            eigener Aktionen; einen <code>FlashMessenger</code> für die Behandlung von
            Kurznachrichten; <code>Json</code> für das verschlüsseln und senden von JSON Antworten;
            einen <code>Redirector</code>, um verschiedene Implementationen, für das Umleiten zu
            internen und externen Seiten, für die Anwendung bereitzustellen und einen
            <code>ViewRenderer</code> um den Prozess des Setzens eines View Objekts im Kontroller
            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>
                    <code>setActionController()</code> wird verwendet um den aktuellen Aktion
                    Kontroller zu setzen.
                </para>
            </listitem>

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

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

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

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

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

            <listitem>
                <para>
                    <code>getName()</code> 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
                    <code>Redirector</code> zurückgegeben; eine Klasse die <code>FooMessage</code>
                    heißt wird einfach sich selbst zurückgeben.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Optional kann eine <code>direct()</code> 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>
            <code>direct()</code> als einen Alias von <code>goto()</code> und erlaubt damit die
            Verwendung des Helfers wie folgt:
        </para>

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

        <para>
            Intern schaut die <code>__call()</code> Methode des Helfer Brokers nach einem Helfer der
            <code>redirector</code> heißt, prüft anschließend ob der Helfer eine definierte
            <code>direct</code> Klasse 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>
<!--
vim:se ts=4 sw=4 et:
-->
