repo_zf1/documentation/manual/de/module_specs/Zend_Controller-Router-Route.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 15103 -->
<!-- Reviewed: no -->
<sect3 id="zend.controller.router.routes.standard">
    <title>Zend_Controller_Router_Route</title>

    <para>
        <classname>Zend_Controller_Router_Route</classname> ist die standardmäßige Framework Route. Sie kombiniert einfache
        Verwendung mit einer flexiblen Routendefinition. Jede Route besteht primär aus URL Übereinstimmungen
        (von statischen und dynamischen Teilen (Variablen)) und kann mit Standardwerten initialisiert werden
        wie auch mit variablen Notwendigkeiten.
    </para>

    <para>
        Angenommen unsere fiktive Anwendung benötigt eine informelle Seite über den Seitenauthor. Es soll möglich
        sein mit dem Browser auf <code>http://domain.com/author/martel</code> zu verweisen um die Informationen über
        diesen "martel" Typ zu sehen. Und die Route für so eine Funktionalität würde so aussehen:
    </para>

    <programlisting role="php"><![CDATA[
$route = new Zend_Controller_Router_Route(
    'author/:username',
    array(
        'controller' => 'profile',
        'action'     => 'userinfo'
    )
);

$router->addRoute('user', $route);
]]>
    </programlisting>

    <para>
        Der ersten Parameter im Konstruktor von <code>http://domain.com/author/martel</code> ist eine
        Routendefinition die einer URL entspricht. Routendefinitionen bestehen aus statischen und dynamischen
        Teilen die durch einen Schrägstrich ('/') seperiert sind. Statische Teile sind nur einfacher Text:
        <code>author</code>. Dynamische Teile, Variablen genannt, werden durch einen vorangestellten
        Doppelpunkt, zum variablen Namen, markiert: <code>:username</code>.
    </para>

    <note>
        <title>Zeichen verwenden</title>
        <para>
            Die aktuelle Implementation erlaubt die Verwendung von allen Zeichen (außer einem Schrägstrich) als
            variablen Identifikator, aber es wird dringend empfohlen das nur Zeichen verwendet werden die auch für
            PHP Veriablen Identifikatoren gültig sind. Zukünftige Implementationen können dieses Verhlaten ändern,
            was zu versteckten Bugs im eigenen Code führen würde.
        </para>
    </note>

    <para>
        Diese Beispielroute wird verglichen wenn der Browser auf <code>http://domain.com/author/martel</code>
        zeigt. In diesem Fall werden alle seine Variablen dem <classname>Zend_Controller_Request</classname> Objekt
        injiziiert und es kann im <code>ProfileController</code> darauf zugegriffen werden. Variablen die von diesem
        Beispiel zurückgegeben werden können als Array mit den folgenden Schlüssel- und Wertepaaren repräsentiert
        werden:
    </para>

    <programlisting role="php"><![CDATA[
$values = array(
    'username'   => 'martel',
    'controller' => 'profile',
    'action'     => 'userinfo'
);
]]>
    </programlisting>

    <para>
        Später sollte <classname>Zend_Controller_Dispatcher_Standard</classname> die <code>userinfoAction()</code> Methode
        der eigenen <code>ProfileController</code> Klasse aufrufen (im Standardmodul) basierend auf diesen
        Werten. Dort ist es möglich alle Variablen durch die <classname>Zend_Controller_Action::_getParam()</classname>
        oder <classname>Zend_Controller_Request::getParam()</classname> Methoden zuzugreifen:
    </para>

    <programlisting role="php"><![CDATA[
public function userinfoAction()
{
    $request = $this->getRequest();
    $username = $request->getParam('username');

    $username = $this->_getParam('username');
}
]]>
    </programlisting>

    <para>
        Eine Routendefinition kann ein weiteres spezielles Zeichen enthalten - eine Wildcard - dargestellt durch ein
        '*' Symbol. Es wird verwendet um Parameter genauso wie im standard Modulrouter zu erhalten (var => Wertepaare
        definiert in der URI). Die folgende Route imitiert mehr oder weniger das Verhalten des Modulrouters:
    </para>

    <programlisting role="php"><![CDATA[
$route = new Zend_Controller_Router_Route(
    ':module/:controller/:action/*',
    array('module' => 'default')
);
$router->addRoute('default', $route);
]]>
    </programlisting>

    <sect4 id="zend.controller.router.routes.standard.variable-defaults">
        <title>Variable Standards</title>

        <para>
            Jede Variable im Router kann einen Standardwert haben und das ist für was der zweite Parameter des
            Konstruktors von <classname>Zend_Controller_Router_Route</classname> verwendet wird. Dieser Parameter ist ein
            Array mit Schlüsseln die Variablennamen repräsentieren und mit Werten als gewünschte Standards:
        </para>

        <programlisting role="php"><![CDATA[
$route = new Zend_Controller_Router_Route(
    'archive/:year',
    array('year' => 2006)
);
$router->addRoute('archive', $route);
]]>
        </programlisting>

        <para>
            Die obige Route entspricht URLs wie <code>http://domain.com/archive/2005</code> und
            <code>http://example.com/archive</code>. Im späteren Fall wird die Variable year einen initialen
            Standardwert von 2006 haben.
        </para>

        <para>
            Dieses Beispiel resultiert darin das eine year Variable in das Anfrage Objekt injiziiert wird. Da keine
            Routinginformation vorhanden ist (es sind keine Kontroller und Aktionsparameter definiert), wird die
            Anwendung zum Standardkontroller und der Aktionsmethode (welche beide in
            <classname>Zend_Controller_Dispatcher_Abstract</classname> definiert sind) weitergeleitet. Um es verwendbarer
            zu machen muß ein gültiger Kontroller und eine gültige aktion als Standard für die Route angegeben
            werden:
        </para>

        <programlisting role="php"><![CDATA[
$route = new Zend_Controller_Router_Route(
    'archive/:year',
    array(
        'year'       => 2006,
        'controller' => 'archive',
        'action'     => 'show'
    )
);
$router->addRoute('archive', $route);
]]>
        </programlisting>

        <para>
            Diese Route führt dazu das an die Methode <code>showAction()</code> der Klasse
            <code>ArchiveController</code> weitergeleitet wird.
        </para>

    </sect4>

    <sect4 id="zend.controller.router.routes.standard.variable-requirements">
        <title>Variable Anforderungen</title>

        <para>
            Man kann einen dritten Parameter dem <classname>Zend_Controller_Router_Route</classname> Konstruktor hinzufügen
            wo variable Anforderungen gesetzt werden können. Diese werden als Teil eines regulären Ausdrucks
            definiert:
        </para>

        <programlisting role="php"><![CDATA[
$route = new Zend_Controller_Router_Route(
    'archive/:year',
    array(
        'year'       => 2006,
        'controller' => 'archive',
        'action'     => 'show'
    ),
    array('year' => '\d+')
);
$router->addRoute('archive', $route);
]]>
        </programlisting>

        <para>
            Mit einer Route die wie oben definiert ist, wird das Routing nur dann stattfinden wenn die year
            Variable nummerische Daten enthält, z.B. <code>http://domain.com/archive/2345</code>.
            Eine URL wie <code>http://example.com/archive/test</code> wird nicht zugeordnet und die Kontrolle wird
            stattdessen an die nächste Route in der Kette übertragen.
        </para>
    </sect4>

    <sect4 id="zend.controller.router.routes.standard.translated-segments">
        <title>Übersetzte Segmente</title>

        <para>
            Die Standardroute unterstützt übersetzte Segmente. Um dieses Feature zu verwenden muß zumindest
            ein Übersetzer (eine Instanz von <classname>Zend_Translate</classname>) auf einem der folgenden Wege
            definiert werden:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    In die Registry mit dem Schlüssel <classname>Zend_Translate</classname> geben.
                </para>
            </listitem>
            <listitem>
                <para>
                    Über die statische Methode
                    <classname>Zend_Controller_Router_Route::setDefaultTranslator()</classname> setzen.
                </para>
            </listitem>
            <listitem>
                <para>
                    Als vierten Parameter im Constructor übergeben.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Standardmäßig wird das Gebietsschema verwendet das in der Instanz von <classname>Zend_Translate</classname>
            verwendet wird. Um es zu überschreiben, kann es (als Instanz von <classname>Zend_Locale</classname> oder
            einem Gebietsschema-String) auf einem der folgenden Wege gesetzt werden:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    In die Registry mit dem Schlüssel <classname>Zend_Locale</classname> geben.
                </para>
            </listitem>
            <listitem>
                <para>
                    Über die statische Methode
                    <classname>Zend_Controller_Router_Route::setDefaultLocale()</classname> setzen.
                </para>
            </listitem>
            <listitem>
                <para>
                    Als fünften Parameter im Constructor übergeben.
                </para>
            </listitem>
            <listitem>
                <para>
                    Als <code>@locale</code> Parameter der assemble Methode übergeben.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Übersetzte Segmente werden in zwei Teile getrennt. Ein fixes Segment dem ein einzelnes
            <code>@</code>-Zeichen vorangestellt wird, der anhand des aktuellen Gebietsschemas übersetzt wird
            und auf der Position des Parameters eingefügt wird. Dynamischen Segmenten wird ein
            <code>:@</code> vorangestellt. Beim Zusammenbauen, wird der gegebene Parameter übersetzt und an der
            Position des Parameters eingefügt. Bei der Überprüfung, wird der übersetzte Parameter von der
            URL wieder in die Nachrichten ID umgewandelt.
        </para>

        <note>
            <title>Nachrichten IDs und eigene Sprachdateien</title>
            <para>
                Normalerweise werden Nachrichten IDs die man in einer seiner Routen verwenden will, bereits in
                einem View Skript oder irgendwo anders verwendet. Um die komplette Kontrolle über sichere
                URLs zu haben, sollte man eine eigene Sprachdatei für die Nachrichten haben die in einer
                Route verwendet werden.
            </para>
        </note>

        <para>
            Nachfolgend ist die einfachste Verwendung gezeigt um eine Standardroute für übersetzte Segmente
            zu Verwenden:
        </para>

        <programlisting role="php"><![CDATA[
// Den Übersetzer vorbereiten
$translator = new Zend_Translate('array', array(), 'en');
$translator->addTranslation(array('archive' => 'archiv',
                                  'year'    => 'jahr',
                                  'month'   => 'monat',
                                  'index'   => 'uebersicht'),
                            'de');

// Das aktuelle Gebietsschema für den Übersetzer setzen
$translator->setLocale('en');

// Als Standard-Übersetzer für Routen setzen
Zend_Controller_Router_Route::setDefaultTranslator($translator);
]]>
        </programlisting>

        <para>
            Dieses Beispiel zeigt die Verwendung von statischen Segmenten:
        </para>

        <programlisting role="php"><![CDATA[
// Die Route erstellen
$route = new Zend_Controller_Router_Route(
    '@archive',
    array(
        'controller' => 'archive',
        'action'     => 'index'
    )
);
$router->addRoute('archive', $route);

// Die URL im Standard-Gebietsschema zusammenbauen: archive
$route->assemble(array());

// Die URL in Deutsch zusammenbauen: archiv
$route->assemble(array());
]]>
        </programlisting>

        <para>
            Man kann dynamische Segmente verwenden um eine Modul-Route, so wie die übersetzte Version,
            zu erstellen:
        </para>

        <programlisting role="php"><![CDATA[
// Die Route erstellen
$route = new Zend_Controller_Router_Route(
    ':@controller/:@action/*',
    array(
        'controller' => 'index',
        'action'     => 'index'
    )
);
$router->addRoute('archive', $route);

// Die URL im Standard-Gebietsschema zusammenbauen: archive/index/foo/bar
$route->assemble(array('controller' => 'archive', 'foo' => 'bar'));

// Die URL in Deutsch zusammenbauen: archiv/uebersicht/foo/bar
$route->assemble(array('controller' => 'archive', 'foo' => 'bar'));
]]>
        </programlisting>

        <para>
            Man kann auch statische und dynamische Segmente mischen:
        </para>

        <programlisting role="php"><![CDATA[
// Die Route erstellen
+$route = new Zend_Controller_Router_Route(
    '@archive/:@mode/:value',
    array(
        'mode'       => 'year'
        'value'      => 2005,
        'controller' => 'archive',
        'action'     => 'show'
    ),
    array('mode'  => '(month|year)'
          'value' => '\d+')
);
$router->addRoute('archive', $route);

// Die URL im Standard-Gebietsschema zusammenbauen: archive/month/5
$route->assemble(array('mode' => 'month', 'value' => '5'));

// Die URL in Deutsch zusammenbauen: archiv/monat/5
$route->assemble(array('mode' => 'month', 'value' => '5', '@locale' => 'de'));
]]>
        </programlisting>
    </sect4>

</sect3>
<!--
vim:se ts=4 sw=4 et:
-->