[DOCUMENTATION]Japanese temporary Controller Router Route Chain

git-svn-id: http://framework.zend.com/svn/framework/standard/trunk@18053 44c647ce-9c0f-0410-b52a-842ac1e357ba

documentation/manual/ja/module_specs/Zend_Controller-Router-Route-Chain.xml

@@ -0,0 +1,222 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Reviewed: no -->
+<!-- EN-Revision: 17592 -->
+<sect3 id="zend.controller.router.routes.chain">
+    <title>Zend_Controller_Router_Route_Chain</title>
+
+    <para>
+        <classname>Zend_Controller_Router_Route_Chain</classname>は、
+        複数のルートを一緒にチェーンできるルートです。
+        これは、たとえばホスト名とルート、パスとルート、または複数のパスとルートをチェーンできます。
+        チェインは、プログラム的に、または、構成ファイルの範囲内で行なえます。
+    </para>
+
+    <note>
+        <title>パラメータ優先度</title>
+        <para>
+            When chaining routes together, the parameters of the outer route
+            have a higher priority than the parameters of the inner route. Thus
+            if you define a controller in the outer and in the inner route,
+            the controller of the outer route will be selected.
+        </para>
+    </note>
+
+    <para>
+        When chaining programatically, there are two ways to achieve this. The
+        first one is to create a new
+        <classname>Zend_Controller_Router_Route_Chain</classname> instance and then
+        calling the <methodname>chain()</methodname> method multiple times with all routes
+        which should be chained together. The other way is to take the first
+        route, e.g. a hostname route, and calling the <methodname>chain()</methodname>
+        method on it with the route which should be appended to it. This
+        will not modify the hostname route, but return a new instance of
+        <classname>Zend_Controller_Router_Route_Chain</classname>, which then has both
+        routes chained together:
+    </para>
+
+    <programlisting language="php"><![CDATA[
+//ルートを２つ作成
+$hostnameRoute = new Zend_Controller_Router_Route_Hostname(...);
+$pathRoute     = new Zend_Controller_Router_Route(...);
+
+// First way, chain them via the chain route
+$chainedRoute = new Zend_Controller_Router_Route_Chain();
+$chainedRoute->chain($hostnameRoute)
+             ->chain($pathRoute);
+
+// Second way, chain them directly
+$chainedRoute = $hostnameRoute->chain($pathRoute);
+]]></programlisting>
+
+    <para>
+        When chaining routes together, their separator is a slash
+        by default. There may be cases when you want to have a different
+        separator:
+    </para>
+
+    <programlisting language="php"><![CDATA[
+//ルートを２つ作成
+$firstRoute  = new Zend_Controller_Router_Route('foo');
+$secondRoute = new Zend_Controller_Router_Route('bar');
+
+// Chain them together with a different separator
+$chainedRoute = $firstRoute->chain($secondRoute, '-');
+
+// Assemble the route: "foo-bar"
+echo $chainedRoute->assemble();
+]]></programlisting>
+
+    <sect4 id="zend.controller.router.routes.chain.config">
+        <title>Zend_Configを介したルートのチェイン</title>
+
+        <para>
+            To chain routes together in a config file, there are additional
+            parameters for the configuration of those. The simpler approach is
+            to use the <property>chains</property> parameters. This one is simply a list
+            of routes, which will be chained with the parent route. Neither the
+            parent- nor the child-route will be added directly to the router but
+            only the resulting chained route. The name of the chained route in
+            the router will be the parent route name and the child route name
+            concatenated with a dash (-) by default. A simple config in <acronym>XML</acronym>
+            would look like this:
+        </para>
+
+        <programlisting language="xml"><![CDATA[
+<routes>
+    <www type="Zend_Controller_Router_Route_Hostname">
+        <route>www.example.com</route>
+        <chains>
+            <language type="Zend_Controller_Router_Route">
+                <route>:language</route>
+                <reqs language="[a-z]{2}">
+                <chains>
+                    <index type="Zend_Controller_Router_Route_Static">
+                        <route></route>
+                        <defaults module="default" controller="index"
+                                  action="index" />
+                    </index>
+                    <imprint type="Zend_Controller_Router_Route_Static">
+                        <route>imprint</route>
+                        <defaults module="default" controller="index"
+                                  action="index" />
+                    </imprint>
+                </chains>
+            </language>
+        </chains>
+    </www>
+    <users type="Zend_Controller_Router_Route_Hostname">
+        <route>users.example.com</route>
+        <chains>
+            <profile type="Zend_Controller_Router_Route">
+                <route>:username</route>
+                <defaults module="users" controller="profile" action="index" />
+            </profile>
+        </chains>
+    </users>
+    <misc type="Zend_Controller_Router_Route_Static">
+        <route>misc</route>
+    </misc>
+</routes>
+]]></programlisting>
+
+        <para>
+            This will result in the three routes <command>www-language-index</command>,
+            <command>www-language-imprint</command> and
+            <command>users-language-profile</command> which will only match based on
+            the hostname and the route <command>misc</command>, which will match with
+            any hostname.
+        </para>
+
+        <para>
+            The alternative way of creating a chained route is via the
+            <property>chain</property> parameter, which can only be used with the
+            chain-route type directly, and also just works in the root level:
+        </para>
+
+        <programlisting language="xml"><![CDATA[
+<routes>
+    <www type="Zend_Controller_Router_Route_Chain">
+        <route>www.example.com</route>
+    </www>
+    <language type="Zend_Controller_Router_Route">
+        <route>:language</route>
+        <reqs language="[a-z]{2}">
+    </language>
+    <index type="Zend_Controller_Router_Route_Static">
+        <route></route>
+        <defaults module="default" controller="index" action="index" />
+    </index>
+    <imprint type="Zend_Controller_Router_Route_Static">
+        <route>imprint</route>
+        <defaults module="default" controller="index" action="index" />
+    </imprint>
+
+    <www-index type="Zend_Controller_Router_Route_Chain">
+        <chain>www, language, index</chain>
+    </www-index>
+    <www-imprint type="Zend_Controller_Router_Route_Chain">
+        <chain>www, language, imprint</chain>
+    </www-imprint>
+</routes>
+]]></programlisting>
+
+        <para>
+            You can also give the <property>chain</property> parameter as array instead
+            of separating the routes with a comma:
+        </para>
+
+        <programlisting language="xml"><![CDATA[
+<routes>
+    <www-index type="Zend_Controller_Router_Route_Chain">
+        <chain>www</chain>
+        <chain>language</chain>
+        <chain>index</chain>
+    </www-index>
+    <www-imprint type="Zend_Controller_Router_Route_Chain">
+        <chain>www</chain>
+        <chain>language</chain>
+        <chain>imprint</chain>
+    </www-imprint>
+</routes>
+]]></programlisting>
+        <para>
+            When you configure chain routes with <classname>Zend_Config</classname> and
+            want the chain name separator to be different from a dash, you
+            need to specify this separator separately:
+        </para>
+
+        <programlisting language="php"><![CDATA[
+$config = new Zend_Config(array(
+    'chainName' => array(
+        'type'   => 'Zend_Controller_Router_Route_Static',
+        'route'  => 'foo',
+        'chains' => array(
+            'subRouteName' => array(
+                'type'     => 'Zend_Controller_Router_Route_Static',
+                'route'    => 'bar',
+                'defaults' => array(
+                    'module'      => 'module',
+                     'controller' => 'controller',
+                     'action'     => 'action'
+                )
+            )
+        )
+    )
+));
+
+//構成追加前にセパレータを設定
+$router->setChainNameSeparator('_separator_')
+
+//構成を追加
+$outer->addConfig($config);
+
+//そしてルート名はこうなります: chainName_separator_subRouteName
+echo $this->_router->assemble(array(), 'chainName_separator_subRouteName');
+
+//検証: /foo/bar をエコーします。
+]]></programlisting>
+    </sect4>
+</sect3>
+<!--
+vim:se ts=4 sw=4 et:
+-->