Merge pull request #685 from symfony-cmf/custom-url-generator

documenting the custom url generator configuration

Author: dbu

bundles/routing/configuration.rst

@@ -542,6 +542,15 @@ content repository service.
 
 .. _reference-config-routing-locales:
 
+``url_generator``
+~~~~~~~~~~~~~~~~~
+
+**type**: ``string`` **default**: ``cmf_routing.generator``
+
+Service id for the DynamicRouter to generate URLs from Route objects. Overwrite
+to a service implementing ``UrlGeneratorInterface`` if you need to customize that
+service.
+
 ``locales``
 ~~~~~~~~~~~
 

bundles/routing/dynamic.rst

@@ -16,6 +16,9 @@ You can configure the route enhancers that decide what controller is used to
 handle the request, to avoid hard coding controller names into your route
 documents.
 
+To fully understand the capabilities of the dynamic router, read also the
+:doc:`routing component documentation <../../components/routing/index>`.
+
 Configuration
 -------------
 
@@ -617,8 +620,8 @@ See the `Sonata Admin extension documentation`_ for more information.
 FrontendLink Sonata Admin Extension
 -----------------------------------
 
-This bundle provides an extension to show a button in Sonata Admin, which links on the actual 
-frontend representation of a document. Documents which implement the ``RouteReferrersReadInterface`` 
+This bundle provides an extension to show a button in Sonata Admin, which links on the actual
+frontend representation of a document. Documents which implement the ``RouteReferrersReadInterface``
 and Routes itself (``Symfony\Component\Routing\Route``) are supported.
 
 To enable the extension in your admin classes, simply define the extension
@@ -636,7 +639,7 @@ configuration in the ``sonata_admin`` section of your project configuration:
                     implements:
                         - Symfony\Cmf\Component\Routing\RouteReferrersReadInterface
                     extends:
-                        - Symfony\Component\Routing\Route 
+                        - Symfony\Component\Routing\Route
 
     .. code-block:: xml
 
@@ -670,19 +673,19 @@ See the `Sonata Admin extension documentation`_ for more information.
 Styling
 ~~~~~~~
 
-Feel free to use your own styles. The frontend link button can be customized 
+Feel free to use your own styles. The frontend link button can be customized
 using the following example CSS rules:
 
 .. code-block:: css
 
     .sonata-admin-menu-item a.sonata-admin-frontend-link {
         font-weight: bold;
     }
-    
+
     .sonata-admin-menu-item a.sonata-admin-frontend-link:before {
         font-family: FontAwesome;
         content: "\f08e";
-    } 
+    }
 
 Customize the DynamicRouter
 ---------------------------

bundles/routing/dynamic_customize.rst

@@ -124,7 +124,6 @@ configuration as follows:
        # app/config/config.yml
        cmf_routing:
            dynamic:
-               enabled: true
                route_provider_service_id: acme_demo.provider.endpoint
 
    .. code-block:: xml
@@ -133,10 +132,7 @@ configuration as follows:
        <?xml version="1.0" encoding="UTF-8" ?>
        <container xmlns="http://symfony.com/schema/dic/services">
            <config xmlns="http://cmf.symfony.com/schema/dic/routing">
-               <dynamic
-                   enabled="true"
-                   route-provider-service-id="acme_demo.provider.endpoint"
-               />
+               <dynamic route-provider-service-id="acme_demo.provider.endpoint"/>
            </config>
        </container>
 
@@ -145,14 +141,50 @@ configuration as follows:
        // app/config/config.php
        $container->loadFromExtension('cmf_routing', array(
            'dynamic' => array(
-              'enabled'                   => true,
               'route_provider_service_id' => 'acme_demo.provider.endpoint',
            ),
        ));
 
 Where ``acme_demo.provider.endpoint`` is the service ID of your route
-provider.  See `Creating and configuring services in the container`_ for
+provider. See `Creating and configuring services in the container`_ for
 information on creating custom services.
 
+Using a Custom URL Generator
+----------------------------
+
+The dynamic router can also generate URLs from route objects. If you need to
+customize this behavior beyond what the
+:ref:`route generate event <components-routing-events>` allows, you can
+implement the ``Symfony\Component\Routing\Generator\UrlGeneratorInterface``
+yourself and configure that service:
+
+.. configuration-block::
+
+   .. code-block:: yaml
+
+       # app/config/config.yml
+       cmf_routing:
+           dynamic:
+               url_generator: routing.my_generator
+
+   .. code-block:: xml
+
+       <!-- app/config/config.xml -->
+       <?xml version="1.0" encoding="UTF-8" ?>
+       <container xmlns="http://symfony.com/schema/dic/services">
+           <config xmlns="http://cmf.symfony.com/schema/dic/routing">
+               <dynamic url-generator="routing.my_generator"/>
+           </config>
+       </container>
+
+   .. code-block:: php
+
+       // app/config/config.php
+       $container->loadFromExtension('cmf_routing', array(
+           'dynamic' => array(
+              'url_generator' => 'routing.my_generator',
+           ),
+       ));
+
 .. _`Creating and configuring services in the container`: http://symfony.com/doc/current/book/service_container.html#creating-configuring-services-in-the-container/
 .. _`PHPCR-ODM`: http://www.doctrine-project.org/projects/phpcr-odm.html