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

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 16180 -->
<!-- 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 <filename>http://domain.com/author/martel</filename>
        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 language="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
        <filename>http://domain.com/author/martel</filename> 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
        <filename>http://domain.com/author/martel</filename> 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 language="php"><![CDATA[
$values = array(
    'username'   => 'martel',
    'controller' => 'profile',
    'action'     => 'userinfo'
);
]]></programlisting>

    <para>
        Später sollte <classname>Zend_Controller_Dispatcher_Standard</classname> die
        <methodname>userinfoAction()</methodname> 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 language="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 language="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 language="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 <filename>http://domain.com/archive/2005</filename>
            und <filename>http://example.com/archive</filename>. 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 Controller und
            Aktionsparameter definiert), wird die Anwendung zum Standardcontroller und der
            Aktionsmethode (welche beide in
            <classname>Zend_Controller_Dispatcher_Abstract</classname> definiert sind)
            weitergeleitet. Um es verwendbarer zu machen muß ein gültiger Controller und eine
            gültige aktion als Standard für die Route angegeben werden:
        </para>

        <programlisting language="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 <methodname>showAction()</methodname> 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 language="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.
            <filename>http://domain.com/archive/2345</filename>. Eine URL wie
            <filename>http://example.com/archive/test</filename> 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 language="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 language="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 language="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 language="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:
-->