documentation for cleaned up routing

Author: dbu

bundles/routing/dynamic.rst

@@ -263,15 +263,20 @@ need content, you can just not set it in the route document.
     from content instances. When resolving the route, the ``_locale`` gets
     into the request and is picked up by the Symfony2 locale system.
 
+    Make sure you configure the valid locales in the configuration so that the
+    bundle can optimally handle locales. The
+    :ref:`configuration reference <reference-config-routing-locales>` lists
+    some options to tweak behaviour and performance.
+
 .. note::
 
-    Under PHPCR-ODM, Routes should never be translatable documents, as one
+    Under PHPCR-ODM, Routes should not be translatable documents, as one
     Route document represents one single url, and serving several translations
     under the same url is not recommended.
 
-    If you need translated URLs, make the locale part of the route name and use
-    several routes for the same content. The route generator will pick the
-    correct route if available.
+    If you need translated URLs, make the ``locale`` part of the route name and
+    create one route per language for the same content. The route generator will
+    pick the correct route if available.
 
 Sonata Doctrine PHPCR-ODM Admin classes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -288,6 +293,10 @@ 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.
 
+The root path to add Routes defaults to the first entry in ``route_basepaths``
+but you can overwrite this with the ``admin_basepath`` if you need a different
+base path.
+
 .. configuration-block::
 
     .. code-block:: yaml

reference/configuration/routing.rst

@@ -305,8 +305,11 @@ phpcr
                     phpcr:
                         enabled: false
                         manager_name: ~
-                        route_basepath: /cms/routes
+                        route_basepaths:
+                            - /cms/routes
+                            - /cms/simple
                         content_basepath: /cms/content
+                        admin_basepath: /cms/routes
                         use_sonata_admin: auto
 
     .. code-block:: xml
@@ -320,10 +323,13 @@ phpcr
                         <phpcr
                             enabled="false"
                             manager-name="null"
-                            route-basepath="/cms/routes"
                             content-basepath="/cms/content"
+                            admin-basepath="/cms/routes"
                             use-sonata-admin="auto"
-                        />
+                        >
+                            <route-basepath>/cms/routes</route-basepath>
+                            <route-basepath>/cms/simple</route-basepath>
+                        </phpcr>
                     </persistence>
                 </dynamic>
             </config>
@@ -337,8 +343,12 @@ phpcr
                     'phpcr' => array(
                         'enabled' => false,
                         'manager_name' => null,
-                        'route_basepath' => '/cms/routes',
+                        'route_basepaths' => array(
+                            '/cms/routes',
+                            '/cms/simple',
+                        )
                         'content_basepath' => '/cms/content',
+                        'admin_basepath' => '/cms/routes',
                         'use_sonata_admin' => 'auto',
                     ),
                 ),
@@ -356,27 +366,37 @@ manager_name
 
 .. include:: partials/persistence_phpcr_manager_name.rst.inc
 
-route_basepath
+route_basepaths
 **************
 
-**type**: ``string`` **default**: ``/cms/routes``
+**type**: ``array`` **default**: ``array('/cms/routes')``
 
-The basepath for routes in the PHPCR tree.
+The basepaths where to look for routes in the PHPCR tree.
 
-If the :doc:`CoreBundle <../../bundles/core/index>` is registered, this will default to
-``%cmf_core.persistence.phpcr.basepath%/routes``.
+If the :doc:`CoreBundle <../../bundles/core/index>` is registered, this will
+default to ``%cmf_core.persistence.phpcr.basepath%/routes``. If the
+:doc:`SimpleCmsBundle <../../bundles/simplecms/index>` is registered as well,
+this will additionally default to ``%cmf_core.persistence.phpcr.basepath%/simple``.
 
 content_basepath
 ****************
 
-**type**: ``content_basepath`` **default**: ``/cms/content``
+**type**: ``string`` **default**: ``/cms/content``
 
 The basepath for content objects in the PHPCR tree. This information is used
 with the sonata admin to offer the correct subtree to select content documents.
 
 If the :doc:`CoreBundle <../../bundles/core/index>` is registered, this will default to
 ``%cmf_core.persistence.phpcr.basepath%/content``.
 
+admin_basepath
+**************
+
+**type**: ``string`` **default**: first value of route_basepaths
+
+The path at which to create routes with Sonata admin. There can be additional
+route basepaths, but you will need your own tools to edit those.
+
 use_sonata_admin
 ****************
 
@@ -487,12 +507,45 @@ content repository service.
     This can be overriden by this option. ORM doesn't have a content
     repository at the moment.
 
+.. _reference-config-routing-locales:
+
 locales
 ~~~~~~~
 
-**type**: ``array`` **default**:
+**type**: ``array`` **default**: ``array()``
 
 To enable multilanguage, set the valid locales in this option.
 
 If the :doc:`CoreBundle <../../bundles/core/index>` is registered, this will default to the value
 of ``cmf_core.locales``.
+
+match_implicit_locale
+~~~~~~~~~~~~~~~~~~~~~
+
+**type**: ``boolean`` **default**: ``true``
+
+Whether the route provider should look for routes without the locale.
+
+For example, when the ``locales`` are ``de`` and ``en`` and the request has the
+url ``de/my/path``, the route provider will not only look for ``de/my/path``,
+``de/my`` and ``de`` but also for ``my/path`` and ``my``. This allows to use a
+single route for multiple languages. This is used for example by the
+:doc:`SimpleCms <../../bundles/simple_cms/index>`.
+
+If you do not need this, disabling the option will gain some performance.
+
+auto_locale_pattern
+~~~~~~~~~~~~~~~~~~~
+
+**type**: ``boolean`` **default**: ``false``
+
+If you enable this option, the LocaleListener will ensure that routes that have
+no locale in their static pattern get the ``auto_locale_pattern`` option set.
+
+.. note::
+
+    Enabling this option will prevent you from having any CMF Routes that match
+    URL without a locale in it.
+
+This is ignored if there are no ``locales`` configured. It makes no sense to
+enable this option when ``match_implicit_locale`` is disabled.