Merge pull request #288 from symfony-cmf/routing

dbu · dbu · commit 7ba6c1be8a40 · 2013-10-05T02:08:46.000-07:00
minor tweaks to the routing book chapter
diff --git a/book/routing.rst b/book/routing.rst
@@ -62,11 +62,12 @@ their configured priority:
         cmf_routing:
             chain:
                 routers_by_id:
-                    # enable the DynamicRouter with high priority to allow overwriting
-                    # configured routes with content
-                    cmf_routing.dynamic_router: 200
+                    # enable the DynamicRouter with a low priority
+                    # this way the non dynamic routes take precedence
+                    # to prevent needless database look ups
+                    cmf_routing.dynamic_router: 20
 
-                    # enable the symfony default router with a lower priority
+                    # enable the symfony default router with a higher priority
                     router.default: 100
 
     .. code-block:: xml
@@ -78,14 +79,15 @@ their configured priority:
 
             <config xmlns="http://cmf.symfony.com/schema/dic/routing">
                 <chain>
-                    <!-- enable the DynamicRouter with high priority to allow overwriting
-                         configured routes with content -->
+                    <!-- enable the DynamicRouter with a low priority
+                         this way the non dynamic routes take precedence
+                         to prevent needless database look ups -->
                     <routers-by-id
                         id="cmf_routing.dynamic_router">
-                        200
+                        20
                     </routers-by-id>
 
-                    <!-- enable the symfony default router with a lower priority -->
+                    <!-- enable the symfony default router with a higher priority -->
                     <routers-by-id
                         id="router.default">
                         100
@@ -99,12 +101,13 @@ their configured priority:
         $container->loadFromExtension('cmf_routing', array(
             'chain' => array(
                 'routers_by_id' => array(
-                    // enable the DynamicRouter with high priority to allow overwriting
-                    // configured routes with content
-                    'cmf_routing.dynamic_router' => 200,
+                    // enable the DynamicRouter with a low priority
+                    // this way the non dynamic routes take precedence
+                    // to prevent needless database look ups
+                    'cmf_routing.dynamic_router' => 20,
 
-                    // enable the symfony default router with a lower priority
-                    'router.default'                     => 100,
+                    // enable the symfony default router with a higher priority
+                    'router.default' => 100,
                 ),
             ),
         ));
@@ -146,21 +149,23 @@ The Default Symfony2 Router
 ---------------------------
 
 Although it replaces the default routing mechanism, Symfony CMF Routing allows
-you to keep using the existing system. In fact, the default routing is enabled
-by default, so you can keep using the routes you declared in your
+you to keep using the existing system. In fact, the standard Symfony2 routing
+is enabled by default, so you can keep using the routes you declared in your
 configuration files, or as declared by other bundles.
 
 .. _start-routing-dynamic-router:
 
 The DynamicRouter
 -----------------
 
-This Router can dynamically load Route instances from a given provider. It
-then uses a matching process to the incoming request to a specific Route,
-which in turn is used to determine which Controller to forward the request to.
+This Router can dynamically load ``Route`` instances from a dynamic source via
+a so called *provider*. In fact it only loads candidate routes. The actual
+matching process is exactly the same as with the standard Symfony2 routing
+mechanism. However the ``DynamicRouter`` additionally is able to determine
+which Controller and Template to use based on the ``Route`` that is matched.
 
-The bundle's default configuration states that ``DynamicRouter`` is disabled
-by default. To activate it, just add the following to your configuration file:
+By default the ``DynamicRouter`` is disabled. To activate it, just add the
+following to your configuration file:
 
 .. configuration-block::
 
@@ -194,7 +199,7 @@ by default. To activate it, just add the following to your configuration file:
         ));
 
 This is the minimum configuration required to load the ``DynamicRouter`` as a
-service, thus making it capable of performing any routing. Actually, when you
+service, thus making it capable of performing routing. Actually, when you
 browse the default pages that come with the Symfony CMF SE, it is the
 ``DynamicRouter`` that matches your requests with the Controllers and
 Templates.
@@ -205,11 +210,13 @@ Getting the Route Object
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 The provider to use can be configured to best suit each implementation's
-needs, and must implement the ``RouteProviderInterface``. As part of this
-bundle, an implementation for `PHPCR-ODM`_ is provided. Also, you can easily
-create your own, as the Router itself is storage agnostic. The default
-provider loads the route at the path in the request and all parent paths to
-allow for some of the path segments being parameters.
+needs. As part of this bundle, an implementation for `Doctrine ORM`_ and
+`PHPCR-ODM`_ is provided. Also, you can easily create your own by simply
+implementing the ``RouteProviderInterface``. Providers are responsible
+for fetching an ordered subset of candidate routes that could match the
+request. For example the default `PHPCR-ODM`_ provider loads the ``Route``
+at the path in the request and all parent paths to allow for some of the
+path segments being parameters.
 
 For more detailed information on this implementation and how you can customize
 or extend it, refer to :doc:`../bundles/routing/introduction`.
@@ -237,23 +244,23 @@ A Route needs to specify which Controller should handle a specific Request.
 The ``DynamicRouter`` uses one of several possible methods to determine it (in
 order of precedence):
 
-* Explicit: The stored Route document itself can explicitly declare the target
-  Controller by specifying the '_controller' value in ``getRouteDefaults()``.
-* By alias: the Route returns a 'type' value in ``getRouteDefaults()``,
+* Explicit: The ``Route`` document itself can explicitly declare the target
+  Controller if one is returned from ``getDefault('_controller')``.
+* By alias: The ``Route`` document returns a value from ``getDefault('type')``,
   which is then matched against the provided configuration from config.yml
-* By class: requires the Route instance to implement ``RouteObjectInterface``
-  and return an object for ``getRouteContent()``. The returned class type is
+* By class: Requires the ``Route`` document to implement ``RouteObjectInterface``
+  and return an object for ``getContent()``. The returned class type is
   then matched against the provided configuration from config.yml.
-* Default: if configured, a default Controller will be used.
+* Default: If configured, a default Controller will be used.
 
 Apart from this, the ``DynamicRouter`` is also capable of dynamically
 specifying which Template will be used, in a similar way to the one used to
 determine the Controller (in order of precedence):
 
 * Explicit: The stored Route document itself can explicitly declare the target
-  Template in ``getRouteDefaults()``.
-* By class: requires the Route instance to implement ``RouteObjectInterface``
-  and return an object for ``getRouteContent()``. The returned class type is
+  Template by returning the name of the template via ``getDefaults('_template')``.
+* By class: Requires the Route instance to implement ``RouteObjectInterface``
+  and return an object for ``getContent()``. The returned class type is
   then matched against the provided configuration from config.yml.
 
 Here's an example of how to configure the above mentioned options:
@@ -267,7 +274,7 @@ Here's an example of how to configure the above mentioned options:
             dynamic:
                 generic_controller: cmf_content.controller:indexAction
                 controllers_by_type:
-                    editablestatic: sandbox_main.controller:indexAction
+                    editable_static: sandbox_main.controller:indexAction
                 controllers_by_class:
                     Symfony\Cmf\Bundle\ContentBundle\Document\StaticContent: cmf_content.controller::indexAction
                 templates_by_class:
@@ -282,8 +289,8 @@ Here's an example of how to configure the above mentioned options:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 
             <config xmlns="http://cmf.symfony.com/schema/dic/routing">
-                <dynamic generic-controller="cmf_content.controllerindexAction">
-                    <controllers-by-type type="editablestatic">
+                <dynamic generic-controller="cmf_content.controller:indexAction">
+                    <controllers-by-type type="editable_static">
                         sandbox_main.controller:indexAction
                     </controllers-by-type>
 
@@ -308,7 +315,7 @@ Here's an example of how to configure the above mentioned options:
             'dynamic' => array(
                 'generic_controller' => 'cmf_content.controller:indexAction',
                 'controllers_by_type' => array(
-                    'editablestatic' => 'sandbox_main.controller:indexAction',
+                    'editable_static' => 'sandbox_main.controller:indexAction',
                 ),
                 'controllers_by_class' => array(
                     'Symfony\Cmf\Bundle\ContentBundle\Document\StaticContent' => 'cmf_content.controller::indexAction',
@@ -338,8 +345,7 @@ Linking a Route with a Model Instance
 Depending on your application's logic, a requested URL may have an associated
 model instance from the database. Those Routes can implement the
 ``RouteObjectInterface``, and optionally return a model instance, that will be
-automatically passed to the Controller as the ``$contentDocument`` variable,
-if declared as parameter.
+automatically passed to the Controller as the ``contentDocument`` method parameter.
 
 Note that a Route can implement the above mentioned interface but still not
 return any model instance, in which case no associated object will be provided.
@@ -367,7 +373,7 @@ configured as follows:
         cmf_routing:
             dynamic:
                 controllers_by_class:
-                    Symfony\Cmf\Component\Routing\RedirectRouteInterface:  cmf_routing.redirect_controller:redirectAction
+                    Symfony\Cmf\Component\Routing\RedirectRouteInterface: cmf_routing.redirect_controller:redirectAction
 
     .. code-block:: xml
 
@@ -464,96 +470,6 @@ in the document.
 For more details, see the
 :ref:`route document section in the RoutingBundle documentation <bundle-routing-document>`.
 
-Integrating with SonataAdmin
-----------------------------
-
-If ``sonata-project/doctrine-phpcr-admin-bundle`` is added to the
-composer.json require section, the route documents are exposed in the
-SonataDoctrinePhpcrAdminBundle. For instructions on how to configure this
-Bundle see :doc:`../bundles/doctrine_phpcr_admin`.
-
-By default, ``use_sonata_admin`` is automatically set based on whether the
-SonataDoctrinePhpcrAdminBundle is available but you can explicitly disable it
-to not have it even if Sonata is enabled, or explicitly enable to get an error
-if Sonata becomes unavailable.
-
-There are a couple of configuration options for the admin. The
-``content_basepath`` points to the root of your content documents.
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # app/config/config.yml
-        cmf_routing:
-            dynamic:
-                persistence:
-                    phpcr:
-                        # use true/false to force using / not using sonata admin
-                        use_sonata_admin: auto
-
-                        # used with Sonata Admin to manage content; defaults to cmf_core.content_basepath
-                        content_basepath: ~
-
-    .. code-block:: xml
-
-        <!-- app/config/config.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-
-        <container xmlns="http://cmf.symfony.com/schema/dic/services"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
-
-            <config xmlns="http://cmf.symfony.com/schema/dic/routing">
-                <dynamic>
-                    <persistence>
-                        <!-- use-sonata-admin: use true/false to force using / not using sonata admin -->
-                        <!-- content-basepath: used with Sonata Admin to manage content;
-                                               defaults to cmf_core.content_basepath -->
-                        <phpcr
-                            use-sonata-admin="auto"
-                            content-basepath="null"
-                        />
-                    </persistence>
-                </dynamic>
-            </config>
-        </container>
-
-    .. code-block:: php
-
-        // app/config/config.php
-        $container->loadFromExtension('cmf_routing', array(
-            'dynamic' => array(
-                'persistence' => array(
-                    'phpcr' => array(
-                        // use true/false to force using / not using sonata admin
-                        'use_sonata_admin' => 'auto',
-
-                        // used with Sonata Admin to manage content; defaults to cmf_core.content_basepath
-                        'content_basepath' => null,
-                    ),
-                ),
-            ),
-        ));
-
-Terms Form Type
----------------
-
-The Routing bundle defines a form type that can be used for classical "accept terms"
-checkboxes where you place URLs in the label. Simply specify
-``cmf_routing_terms_form_type`` as the form type name and
-specify a label and an array with ``content_ids`` in the options::
-
-    $form->add('terms', 'cmf_routing_terms_form_type', array(
-        'label' => 'I have seen the <a href="%team%">Team</a> and <a href="%more%">More</a> pages ...',
-        'content_ids' => array(
-            '%team%' => '/cms/content/static/team',
-            '%more%' => '/cms/content/static/more'
-        ),
-    ));
-
-The form type automatically generates the routes for the specified content and
-passes the routes to the trans twig helper for replacement in the label.
-
 Further Notes
 -------------
 
@@ -564,5 +480,6 @@ For more information on the Routing component of Symfony CMF, please refer to:
 * Symfony2's `Routing`_ component page
 * :doc:`../cookbook/handling_multilang_documents` for some notes on multilingual routing
 
-.. _`PHPCR-ODM`: https://github.com/doctrine/phpcr-odm
+.. _`Doctrine ORM`: http://www.doctrine-project.org/projects/orm.html
+.. _`PHPCR-ODM`: http://www.doctrine-project.org/projects/phpcr-odm.html
 .. _`Routing`: http://symfony.com/doc/current/components/routing/introduction.html
diff --git a/bundles/routing/dynamic.rst b/bundles/routing/dynamic.rst
@@ -267,13 +267,65 @@ get an error if Sonata becomes unavailable.
 Sonata admin is using the ``content_basepath`` to show the tree of content to
 select the route target.
 
-See the :ref:`routing configuration reference PHPCR section <reference-configuration-routing-persistence-phpcr>`
-for more details.
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/config.yml
+        cmf_routing:
+            dynamic:
+                persistence:
+                    phpcr:
+                        # use true/false to force using / not using sonata admin
+                        use_sonata_admin: auto
+
+                        # used with Sonata Admin to manage content; defaults to %cmf_core.basepath%/content
+                        content_basepath: ~
+
+    .. code-block:: xml
+
+        <!-- app/config/config.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+
+        <container xmlns="http://cmf.symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+
+            <config xmlns="http://cmf.symfony.com/schema/dic/routing">
+                <dynamic>
+                    <persistence>
+                        <!-- use-sonata-admin: use true/false to force using / not using sonata admin -->
+                        <!-- content-basepath: used with Sonata Admin to manage content;
+                                               defaults to %cmf_core.basepath%/content -->
+                        <phpcr
+                            use-sonata-admin="auto"
+                            content-basepath="null"
+                        />
+                    </persistence>
+                </dynamic>
+            </config>
+        </container>
+
+    .. code-block:: php
+
+        // app/config/config.php
+        $container->loadFromExtension('cmf_routing', array(
+            'dynamic' => array(
+                'persistence' => array(
+                    'phpcr' => array(
+                        // use true/false to force using / not using sonata admin
+                        'use_sonata_admin' => 'auto',
+
+                        // used with Sonata Admin to manage content; defaults to %cmf_core.basepath%/content
+                        'content_basepath' => null,
+                    ),
+                ),
+            ),
+        ));
 
 Doctrine ORM integration
 ------------------------
 
-Alternatively, you can use the Doctrine ORM provider by specifying the
+Alternatively, you can use the `Doctrine ORM`_ provider by specifying the
 ``persistence.orm`` part of the configuration. It does a similar job but, as
 the name indicates, loads ``Route`` entities from an ORM database.
 
@@ -487,6 +539,7 @@ Read on in the chapter :doc:`customizing the dynamic router <dynamic_customize>`
 
 .. _`CMF sandbox`: https://github.com/symfony-cmf/cmf-sandbox
 .. _`CMF Routing component`: https://github.com/symfony-cmf/Routing
-.. _`PHPCR-ODM`: https://github.com/doctrine/phpcr-odm
+.. _`Doctrine ORM`: http://www.doctrine-project.org/projects/orm.html
+.. _`PHPCR-ODM`: http://www.doctrine-project.org/projects/phpcr-odm.html
 .. _`Sonata Admin extension documentation`: http://sonata-project.org/bundles/admin/master/doc/reference/extensions.html
 .. _`URL generating capabilities of Symfony2`: http://symfony.com/doc/current/book/routing.html#generating-urls
diff --git a/bundles/routing/dynamic_customize.rst b/bundles/routing/dynamic_customize.rst
@@ -151,4 +151,4 @@ provider.  See `Creating and configuring services in the container`_ for
 information on creating custom services.
 
 .. _`Creating and configuring services in the container`: http://symfony.com/doc/current/book/service_container.html#creating-configuring-services-in-the-container/
-.. _`PHPCR-ODM`: https://github.com/doctrine/phpcr-odm
+.. _`PHPCR-ODM`: http://www.doctrine-project.org/projects/phpcr-odm.html
diff --git a/bundles/routing/introduction.rst b/bundles/routing/introduction.rst
