<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- 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 <acronym>URL</acronym> Ü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
        <classname>Zend_Controller_Router_Route</classname> ist eine Routendefinition die einer
        <acronym>URL</acronym> entspricht. Routendefinitionen bestehen aus statischen und
        dynamischen Teilen die durch einen Schrägstrich ('/') seperiert sind. Statische Teile sind
        nur einfacher Text: <command>author</command>. Dynamische Teile, Variablen genannt, werden
        durch einen vorangestellten Doppelpunkt, zum variablen Namen, markiert:
        <command>:username</command>.
    </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 <acronym>PHP</acronym> 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 <classname>ProfileController</classname> 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
        <classname>ProfileController</classname> Klasse aufrufen (im Standardmodul) basierend auf
        diesen Werten. Dort ist es möglich alle Variablen durch die
        <methodname>Zend_Controller_Action::_getParam()</methodname> oder
        <methodname>Zend_Controller_Request::getParam()</methodname> 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 <acronym>URI</acronym>). 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 <acronym>URL</acronym>s 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 <classname>ArchiveController</classname> 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 <acronym>URL</acronym> 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
                    <methodname>Zend_Controller_Router_Route::setDefaultTranslator()</methodname>
                    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
                    <methodname>Zend_Controller_Router_Route::setDefaultLocale()</methodname>
                    setzen.
                </para>
            </listitem>

            <listitem>
                <para>
                    Als fünften Parameter im Constructor übergeben.
                </para>
            </listitem>

            <listitem>
                <para>
                    Als <command>@locale</command> Parameter der assemble Methode übergeben.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Übersetzte Segmente werden in zwei Teile getrennt. Ein fixes Segment dem ein einzelnes
            <emphasis>@</emphasis>-Zeichen vorangestellt wird, der anhand des aktuellen
            Gebietsschemas übersetzt wird und auf der Position des Parameters eingefügt wird.
            Dynamischen Segmenten wird ein <command>:@</command> 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 <acronym>URL</acronym> 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 <acronym>URL</acronym>s 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(
        'adapter' => 'array',
        'content' => array(),
        'locale'  => 'en'
    )
);
$translator->addTranslation(
    array(
        'content' =>
            array(
                'archive' => 'archiv',
                'year'    => 'jahr',
                'month'   => 'monat',
                'index'   => 'uebersicht'
            ),
        'locale' => '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>