diff --git a/book/routing.rst b/book/routing.rst index f2c699d9..429d143b 100644 --- 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: - + - 200 + 20 - + 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,8 +149,8 @@ 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: @@ -155,12 +158,14 @@ configuration files, or as declared by other bundles. 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"> - - + + sandbox_main.controller:indexAction @@ -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 `. -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 - - - - - - - - - - - - - - - - - - .. 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 Team and More 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 index a9dedcef..40031fbf 100644 --- 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 ` -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 + + + + + + + + + + + + + + + + + + .. 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 ` .. _`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 \ No newline at end of file diff --git a/bundles/routing/dynamic_customize.rst b/bundles/routing/dynamic_customize.rst index 2139e300..7276d409 100644 --- 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 index 24236211..3958959a 100644 --- a/bundles/routing/introduction.rst +++ b/bundles/routing/introduction.rst @@ -30,11 +30,6 @@ ORM, as well as a controller for redirection routes. .. index:: RoutingBundle .. index:: Routing -Dependencies ------------- - -* `Symfony CMF routing`_ - ChainRouter ----------- @@ -96,7 +91,6 @@ For more information on Routing in the Symfony CMF, please refer to: * Symfony2's `Routing`_ component documentation. .. _`RoutingBundle`: https://github.com/symfony-cmf/RoutingBundle#readme -.. _`Symfony CMF routing`: https://github.com/symfony-cmf/Routing#readme -.. _`PHPCR-ODM`: https://github.com/doctrine/phpcr-odm +.. _`PHPCR-ODM`: http://www.doctrine-project.org/projects/phpcr-odm.html .. _`documentation for DependencyInjection tags`: http://symfony.com/doc/2.1/reference/dic_tags.html .. _`Routing`: http://symfony.com/doc/current/components/routing/introduction.html