<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect1 id="zend.controller.dispatcher">
    <title>Der Dispatcher</title>

    <sect2 id="zend.controller.dispatcher.overview">
        <title>Überblick</title>

        <para>
            Dispatching ist der Prozess, das Request Objekt
            <classname>Zend_Controller_Request_Abstract</classname> zu übernehmen, die dort
            enthaltenen Modul, Controller und Aktion Namen sowie die optionalen Parameter zu
            extrahieren und dann den Controller zu instanzieren und die Aktion dieses Controllers
            aufzurufen. Wenn kein Modul, kein Controller oder keine Aktion gefunden wurde, werden
            dafür Standardwerte verwendet.
            <classname>Zend_Controller_Dispatcher_Standard</classname> legt
            <emphasis>index</emphasis> für jede der Controller und Action Standardwerte fest und
            <emphasis>default</emphasis> für den Standardwert des Moduls, erlaubt dem Entwickler
            aber auch, diese durch Verwendung der <methodname>setDefaultController()</methodname>,
            <methodname>setDefaultAction()</methodname> und
            <methodname>setDefaultModule()</methodname> Methoden zu verändern.
        </para>

        <note>
            <title>Standard Module</title>

            <para>
                Bei der Erstellung von modularen Anwendungen kann es sein das man auch einen
                Namespace für eigene Standard Module haben will (die Standardkonfiguration ist, dass
                das Standardmodul <emphasis>keinen</emphasis> Namensraum hat). Ab 1.5.0, kann das
                durch Spezifizierung von <property>prefixDefaultModule</property> auf
                <constant>TRUE</constant>, entweder im Front Controller oder im Dispatcher, getan
                werden:
            </para>

            <programlisting language="php"><![CDATA[
// Im Front Controller:
$front->setParam('prefixDefaultModule', true);

// Im Dispatcher:
$dispatcher->setParam('prefixDefaultModule', true);
]]></programlisting>

            <para>
                Das erlaubt es existierende Module als Standardmodule für eine Anwendung
                wiederzuverwenden.
            </para>
        </note>

        <para>
            Dispatching läuft innerhalb einer Schleife im Front Controller ab. Vor dem Dispatching
            fragt der Front Controller den Request ab, um benutzerspezifizierte Werte für Modul,
            Controller, Aktion und optionale Parameter zu finden. Dann startet er die Dispatch
            Schleife, um die Anfrage zu verarbeiten.
        </para>

        <para>
            Zu Beginn jeden Durchlaufes setzt er im Request Objekt einen Schalter, der angibt, dass
            die Aktion verarbeitet worden ist. Wenn eine Aktion oder ein pre- oder postDispatch
            Plugin diesen Schalter zurücksetzt, wird die Dispatch Schleife fortgesetzt und
            versucht, die neue Anfrage zu verarbeiten. Durch Ändern des Controllers und / oder der
            Aktion im Request Objekt und Zuürcksetzen des Verarbeitungsstatus, kann der Entwickler
            eine zu durchlaufende Anfragekette definieren.
        </para>

        <para>
            Die Controller Methode, die solch eine Verarbeitung kontrolliert lautet
            <methodname>_forward()</methodname>; rufe diese Methode von einer beliebigen
            <methodname>preDispatch()</methodname>, <methodname>postDispatch()</methodname>
            oder Aktionsmethode auf und übergebe Aktion, Controller, Modul und beliebige optionale
            Parameter, die du zur neuen Aktion übersenden möchtest:
        </para>

        <programlisting language="php"><![CDATA[
public function fooAction()
{
    // weiterleiten zu einer anderen Aktion im aktuellen Controller und Modul:
    $this->_forward('bar', null, null, array('baz' => 'bogus'));
}

public function barAction()
{
    // Weiterleiten zu einer Aktion in einem anderen Controller:
    // FooController::bazAction(), im aktuellen Modul:
    $this->_forward('baz', 'foo', null, array('baz' => 'bogus'));
}

public function bazAction()
{
    // weiterleiten zu einer Aktion in einem anderen Controller in einem
    // anderen Modul Foo_BarController::bazAction():
    $this->_forward('baz', 'bar', 'foo', array('baz' => 'bogus'));
}
]]></programlisting>
    </sect2>

    <sect2 id="zend.controller.dispatcher.subclassing">
        <title>Erben vom Dispatcher</title>

        <para>
            <classname>Zend_Controller_Front</classname> ruft zuerst den Router auf, um die erste
            Aktion für den Request zu ermitteln. Danach startet es die Dispatch Schleife, welche
            den Dispatcher aufruft, um die Aktion zu verarbeiten.
        </para>

        <para>
            Der Dispatcher benötigt eine Vielzahl von Daten um seine Arbeit zu erledigen - er muß
            wissen wie die Namen von Controller und Aktionen formatiert werden sollen, wo nach
            Dateien der Controller Klassen gesucht wird, ob ein übergebener Modulname gültig ist
            oder nicht, und eine <acronym>API</acronym> um festzustellen ob eine gegebene Anfrage,
            basierend auf den anderen vorhandenen Informationen, bearbeitbar ist.
        </para>

        <para>
            <classname>Zend_Controller_Dispatcher_Interface</classname> definiert die folgenden
            Methoden die für jede Dispatcher Implementierung benötigt werden:
        </para>

        <programlisting language="php"><![CDATA[
interface Zend_Controller_Dispatcher_Interface
{
    /**
     * Format a string into a controller class name.
     *
     * @param string $unformatted
     * @return string
     */
    public function formatControllerName($unformatted);

    /**
     * Format a string into an action method name.
     *
     * @param string $unformatted
     * @return string
     */
    public function formatActionName($unformatted);

    /**
     * Determine if a request is dispatchable
     *
     * @param  Zend_Controller_Request_Abstract $request
     * @return boolean
     */
    public function isDispatchable(
        Zend_Controller_Request_Abstract $request
    );

    /**
     * Set a user parameter (via front controller, or for local use)
     *
     * @param string $name
     * @param mixed $value
     * @return Zend_Controller_Dispatcher_Interface
     */
    public function setParam($name, $value);

    /**
     * Set an array of user parameters
     *
     * @param array $params
     * @return Zend_Controller_Dispatcher_Interface
     */
    public function setParams(array $params);

    /**
     * Retrieve a single user parameter
     *
     * @param string $name
     * @return mixed
     */
    public function getParam($name);

    /**
     * Retrieve all user parameters
     *
     * @return array
     */
    public function getParams();

    /**
     * Clear the user parameter stack, or a single user parameter
     *
     * @param null|string|array single key or array of keys for params to clear
     * @return Zend_Controller_Dispatcher_Interface
     */
    public function clearParams($name = null);

    /**
     * Set the response object to use, if any
     *
     * @param Zend_Controller_Response_Abstract|null $response
     * @return void
     */
    public function setResponse(
        Zend_Controller_Response_Abstract $response = null
    );

    /**
     * Retrieve the response object, if any
     *
     * @return Zend_Controller_Response_Abstract|null
     */
    public function getResponse();

    /**
     * Add a controller directory to the controller directory stack
     *
     * @param string $path
     * @param string $args
     * @return Zend_Controller_Dispatcher_Interface
     */
    public function addControllerDirectory($path, $args = null);

    /**
     * Set the directory (or directories) where controller files are stored
     *
     * @param string|array $dir
     * @return Zend_Controller_Dispatcher_Interface
     */
    public function setControllerDirectory($path);

    /**
     * Return the currently set directory(ies) for controller file lookup
     *
     * @return array
     */
    public function getControllerDirectory();

    /**
     * Dispatch a request to a (module/)controller/action.
     *
     * @param  Zend_Controller_Request_Abstract $request
     * @param  Zend_Controller_Response_Abstract $response
     * @return Zend_Controller_Request_Abstract|boolean
     */
    public function dispatch(
        Zend_Controller_Request_Abstract $request,
        Zend_Controller_Response_Abstract $response
    );

    /**
     * Whether or not a given module is valid
     *
     * @param string $module
     * @return boolean
     */
    public function isValidModule($module);

    /**
     * Retrieve the default module name
     *
     * @return string
     */
    public function getDefaultModule();

    /**
     * Retrieve the default controller name
     *
     * @return string
     */
    public function getDefaultControllerName();

    /**
     * Retrieve the default action
     *
     * @return string
     */
    public function getDefaultAction();
}
]]></programlisting>

        <para>
            In den meisten Fällen sollte trotzdem einfach die abstrakte Klasse
            <classname>Zend_Controller_Dispatcher_Abstract</classname> erweitert werden, und welcher
            jede davon schon definiert wurde, oder
            <classname>Zend_Controller_Dispatcher_Standard</classname> um Funktionalitäten des
            Standard Dispatchers zu modifizieren.
        </para>

        <para>
            Mögliche Gründe um den Dispatcher zu erweitern beinhaltet den Wunsch eine anderes
            Klassen oder Methoden Namensschema in den eigenen Aktion Controllern zu verwenden, oder
            den Wunsch ein anderes Verarbeitungs Paradigma wie das Verarbeiten zu Aktionsdateien
            unter den Controller Verzeichnissen (statt auf Klassen Methoden zu verarbeiten).
        </para>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->