document new way of generating routes (#864)

* document new way of generating routes

Co-Authored-By: Jeroen Thora <[email protected]>

Author: dbu

bundles/core/templating.rst

@@ -112,6 +112,13 @@ Helper methods
 Code examples
 .............
 
+.. versionadded:: 2.3
+
+    Since `symfony-cmf/routing: 2.3.0`, the route document should be passed in
+    the route parameters as `_route_object`, and the special route name
+    `cmf_routing_object` is to be used. When using older versions of routing,
+    you need to pass the route document as route name.
+
 .. configuration-block::
 
     .. code-block:: html+jinja
@@ -121,16 +128,16 @@ Code examples
         {% if cmf_is_published(page) %}
             {% set prev = cmf_prev_linkable(page) %}
             {% if prev %}
-                <a href="{{ path(prev) }}">prev</a>
+                <a href="{{ path('cmf_routing_object', {_route_object: prev}) }}">prev</a>
             {% endif %}
 
             {% set next = cmf_next_linkable(page) %}
             {% if next %}
-                <span style="float: right; padding-right: 40px;"><a href="{{ path(next) }}">next</a></span>
+                <span style="float: right; padding-right: 40px;"><a href="{{ path('cmf_routing_object', {_route_object: next}) }}">next</a></span>
             {%  endif %}
 
             {% for news in cmf_children(parent=cmfMainContent, class='AppBundle\\Document\\NewsItem')|reverse %}
-                <li><a href="{{ path(news) }}">{{ news.title }}</a> ({{ news.publishStartDate | date('Y-m-d')  }})</li>
+                <li><a href="{{ path('cmf_routing_object', {_route_object: news}) }}">{{ news.title }}</a> ({{ news.publishStartDate | date('Y-m-d')  }})</li>
             {% endfor %}
 
             {% if 'de' in cmf_document_locales(page) %}
@@ -158,19 +165,28 @@ Code examples
         <?php if $view['cmf']->isPublished($page) : ?>
             <?php $prev = $view['cmf']->getPrev($page) ?>
             <?php if ($prev) : ?>
-                <a href="<?php echo $view['router']->generate($prev) ?>">prev</a>
+                <a href="<?php echo $view['router']->generate(
+                                        RouteObjectInterface::OBJECT_BASED_ROUTE_NAME,
+                                        [RouteObjectInterface::ROUTE_OBJECT => $prev]
+                ) ?>">prev</a>
             <?php endif ?>
 
             <?php $next = $view['cmf']->getNext($page) ?>
             <?php if ($next) : ?>
                 <span style="float: right; padding-right: 40px;">
-                    <a href="<?php echo $view['router']->generate($next) ?>">next</a>
+                    <a href="<?php echo $view['router']->generate(
+                                        RouteObjectInterface::OBJECT_BASED_ROUTE_NAME,
+                                        [RouteObjectInterface::ROUTE_OBJECT => $next]
+                    ) ?>">next</a>
                 </span>
             <?php endif ?>
 
             <?php foreach (array_reverse($view['cmf']->getChildren($page)) as $news) : ?>
                 <li>
-                    <a href="<?php echo $view['router']->generate($news) ?>"><?php echo $news->getTitle() ?></a>
+                    <a href="<?php echo $view['router']->generate(
+                                        RouteObjectInterface::OBJECT_BASED_ROUTE_NAME,
+                                        [RouteObjectInterface::ROUTE_OBJECT => $news]
+                    ) ?>"><?php echo $news->getTitle() ?></a>
                     (<?php echo date('Y-m-d', $news->getPublishStartDate()) ?>)
                 </li>
             <?php endforeach ?>

bundles/routing/dynamic.rst

@@ -497,24 +497,33 @@ also responsible for generating an URL from a route and its parameters. The
     All Twig examples below are given with the ``path`` function that generates
     the URL without domain, but will work with the ``url`` function as well.
 
-    Also, you can specify parameters to the generator, which will be used if
-    the route contains a dynamic pattern or otherwise will be appended as
+    Also, you can specify other parameters to the generator, which will be used
+    if the route contains a dynamic pattern or otherwise will be appended as
     query string, just like with the standard routing.
 
-You can use a ``Route`` object as the name parameter of the generating method.
-This will look as follows:
+.. versionadded:: 2.3
+
+    Since `symfony-cmf/routing: 2.3.0`, the route document should be passed in
+    the route parameters as `_route_object`, and the special route name
+    `cmf_routing_object` is to be used. When using older versions of routing,
+    you need to pass the route document as route name.
+
+You can use a ``Route`` object directly with the router:
 
 .. configuration-block::
 
     .. code-block:: html+jinja
 
         {# myRoute is an object of class Symfony\Component\Routing\Route #}
-        <a href="{{ path(myRoute) }}">Read on</a>
+        <a href="{{ path('cmf_routing_object', {_route_object: myRoute}) }}">Read on</a>
 
     .. code-block:: html+php
 
         <!-- $myRoute is an object of class Symfony\Component\Routing\Route -->
-        <a href="<?php echo $view['router']->generate($myRoute) ?>">
+        <a href="<?php echo $view['router']->generate(
+            RouteObjectInterface::OBJECT_BASED_ROUTE_NAME,
+            [RouteObjectInterface::ROUTE_OBJECT => $myRoute])
+        ?>">
             Read on
         </a>
 
@@ -553,12 +562,15 @@ object that implements this interface and provides a route for it:
     .. code-block:: html+jinja
 
         {# myContent implements RouteReferrersInterface #}
-        <a href="{{ path(myContent) }}>Read on</a>
+        <a href="{{ path('cmf_routing_object', {_route_object: myContent}) }}>Read on</a>
 
     .. code-block:: html+php
 
         <!-- $myContent implements RouteReferrersInterface -->
-        <a href="<?php echo $view['router']->generate($myContent) ?>">
+        <a href="<?php echo $view['router']->generate(
+            RouteObjectInterface::OBJECT_BASED_ROUTE_NAME,
+            [RouteObjectInterface::ROUTE_OBJECT => $myContent])
+        ?>">
             Home
         </a>
 
@@ -575,14 +587,14 @@ an empty route name and tries to find a content implementing the
 
     .. code-block:: html+jinja
 
-        <a href="{{ path(null, {'content_id': '/cms/content/my-content'}) }}>
+        <a href="{{ path('cmf_routing_object', {'content_id': '/cms/content/my-content'}) }}>
             Read on
         </a>
 
     .. code-block:: html+php
 
         <!-- $myContent implements RouteReferrersInterface -->
-        <a href="<?php echo $view['router']->generate(null, [
+        <a href="<?php echo $view['router']->generate('cmf_routing_object', [
             'content_id' => '/cms/content/my-content',
         ]) ?>">
             Home

components/routing/dynamic.rst

@@ -193,38 +193,38 @@ a route.
 
 The generator method looks like this::
 
-    public function generate($name, $parameters = array(), $referenceType = self::ABSOLUTE_PATH);
+    public function generate($name, $parameters = [], $referenceType = self::ABSOLUTE_PATH);
 
 In Symfony core, the ``$name`` has to be a string with the configured name
 of the route to generate. The CMF routing component adds generators that handle
 alternative semantics of ``$name``.
 
+.. versionadded:: 2.3
+
+    Since `symfony-cmf/routing: 2.3.0`, the route document should be passed in
+    the route parameters as `_route_object`, and the special route name
+    `cmf_routing_object` is to be used. When using older versions of routing,
+    you need to pass the route document as route name.
+
 The ``ProviderBasedGenerator`` extends Symfony's default
 :class:`Symfony\\Component\\Routing\\Generator\\UrlGenerator` (which, in turn,
 implements :class:`Symfony\\Component\\Routing\\Generator\\UrlGeneratorInterface`)
-and - if the name is not already a ``Route`` object - loads the Route from the
-Route provider. It then lets the core logic generate the URL from that ``Route``.
+and asks the route provider to find a route based on the name and parameters. It
+then lets the core logic generate the URL from that ``Route``.
 
 The CMF component also includes the ``ContentAwareGenerator``, which extends
-the ``ProviderBasedGenerator``, that checks if ``$name`` is an object
+the ``ProviderBasedGenerator``, that checks if ``_route_object`` parameter is an object
 implementing ``RouteReferrersReadInterface``. If it is, it gets the ``Route``
 from that object. Using the ``ContentAwareGenerator``, you can generate URLs
 for your content in three ways:
 
-* Either pass a ``Route`` object as $name
-* Or pass a ``RouteReferrersInterface`` object that is your content as $name
+* Either pass a ``Route`` object as the ``_route_object`` parameter
+* Or pass a ``RouteReferrersInterface`` object that is your content as the ``_route_object`` parameter
 * Or provide an implementation of ``ContentRepositoryInterface`` and pass the id
-  of the content object as parameter ``content_id`` and ``null`` as $name.
-
-If you want to implement your own generator for ``$name`` values that are not
-strings, you need to implement the ``ChainedRouterInterface`` and implement the
-``supports($name)`` method to tell the ``ChainRouter`` if your router can
-accept this ``$name`` to generate a URL.
+  of the content object as parameter ``content_id`` and ``cmf_routing_object`` as $name.
 
-In order to let the DynamicRouter know if it can try to generate a route with an
-object, generators that are able to do so have to implement the
-``VersatileGeneratorInterface`` and return true for the ``supports($route)``
-call  with any object they can handle.
+If you want to implement your own generator, implement the ``VersatileGeneratorInterface``
+to get better debug messages for when a route can not be generated.
 
 .. _`Event Dispatcher`: https://symfony.com/doc/current/components/event_dispatcher/index.html
 .. _`How to create an Event Listener`: https://symfony.com/doc/current/cookbook/event_dispatcher/event_listener.html

tutorial/content-to-controllers.rst

@@ -7,7 +7,8 @@ Make your content route aware
 In the :doc:`getting-started` section, you defined your `Post` and `Page` documents as
 implementing the ``RoutesReferrersReadInterface``. This interface enables the routing system
 to retrieve routes which refer to the object implementing this interface, and this enables
-the system to generate a URL (for example when you use ``{{ path(mydocument) }}`` in Twig).
+the system to generate a URL (for example when you use
+``{{ path('cmf_routing_object', {_route_object: mydocument}) }}`` in Twig).
 
 Earlier you did not have the RoutingBundle installed, so you could not add the mapping.
 
@@ -141,7 +142,7 @@ Add a corresponding template (note that this works because you use the
         <h2>Our Blog Posts</h2>
         <ul>
             {% for post in posts %}
-                <li><a href="{{ path(post) }}">{{ post.title }}</a></li>
+                <li><a href="{{ path('cmf_routing_object', {_route_object: post}) }}">{{ post.title }}</a></li>
             {% endfor %}
         </ul>
 
@@ -154,7 +155,10 @@ Add a corresponding template (note that this works because you use the
         <ul>
             <?php foreach($posts as $post) : ?>
                 <li>
-                    <a href="<?php echo $view['router']->generate($post) ?>">
+                    <a href="<?php echo $view['router']->generate(
+                                        RouteObjectInterface::OBJECT_BASED_ROUTE_NAME,
+                                        [RouteObjectInterface::ROUTE_OBJECT => $post]
+                    ) ?>">
                         <?php echo $post->getTitle() ?>
                     </a>
                 </li>

tutorial/getting-started.rst

@@ -212,7 +212,7 @@ be referenceable and in addition will automatically set the date using the
 Both the ``Post`` and ``Page`` classes implement the
 ``RouteReferrersReadInterface``. This interface enables the
 :ref:`DynamicRouter to generate URLs <bundles-routing-dynamic-generator>` from
-instances of these classes. (for example with ``{{ path(content) }}`` in Twig).
+instances of these classes. (for example with ``{{ path('cmf_routing_object', {_route_object: content}) }}`` in Twig).
 
 Repository Initializer
 ~~~~~~~~~~~~~~~~~~~~~~