Skip to content
This repository was archived by the owner on Sep 16, 2021. It is now read-only.

minor tweaks to the routing book chapter #288

Merged
merged 1 commit into from
Oct 5, 2013
Merged

minor tweaks to the routing book chapter #288

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
183 changes: 50 additions & 133 deletions book/routing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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,
),
),
));
Expand Down Expand Up @@ -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::

Expand Down Expand Up @@ -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.
Expand All @@ -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`.
Expand Down Expand Up @@ -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:
Expand All @@ -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:
Expand All @@ -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>

Expand All @@ -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',
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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
-------------

Expand All @@ -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
61 changes: 57 additions & 4 deletions bundles/routing/dynamic.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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
2 changes: 1 addition & 1 deletion bundles/routing/dynamic_customize.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Loading