Merge pull request #1516 from caponica/routing-doc2

Updated routing.rst to clarify and expand it

Resources/doc/reference/routing.rst

@@ -12,23 +12,37 @@ The ``Admin`` class contains two routing methods:
 Routing Definition
 ------------------
 
-You can set a ``baseRouteName`` property inside your ``Admin`` class, which
-represents the route prefix.
+Route names
+^^^^^^^^^^^
+
+You can set a ``baseRouteName`` property inside your ``Admin`` class. This
+represents the route prefix, to which an underscore and the action name will 
+be added to generate the actual route names. Note: this is the internal *name* 
+given to a route (it has nothing to do with the route's visible *URL*).
 
 .. code-block:: php
 
     <?php
     class PostAdmin extends Admin
     {
-        protected $baseRouteName = 'news_post_admin';
+        protected $baseRouteName = 'sonata_post';
+        // will result in routes named:
+        //   sonata_post_list
+        //   sonata_post_create
+        //   etc..
     }
 
-If no ``baseRouteName`` is defined then the Admin will pick one for you, built
-in the following format: 'admin_vendor_bundlename_entityname_action'. If the
-Admin fails to find the best baseRouteName then a ``RuntimeException`` will
-be thrown.
+If no ``baseRouteName`` is defined then the Admin will generate one for you, 
+based on the following format: 'admin_vendor_bundlename_entityname' so you will have
+route names for your actions like 'admin_vendor_bundlename_entityname_list'.
+
+If the Admin fails to find a baseRouteName for your Admin class a ``RuntimeException`` 
+will be thrown with a related message.
 
-You can also use ``baseRoutePattern`` to set a custom URL for a given ``Admin`` class.
+Route patterns (URLs)
+^^^^^^^^^^^^^^^^^^^^^
+
+You can use ``baseRoutePattern`` to set a custom URL for a given ``Admin`` class.
 
 For example, to use ``http://yourdomain.com/admin/foo`` as the base URL for 
 the ``FooAdmin`` class (instead of the default of ``http://yourdomain.com/admin/vendor/bundle/foo``)
@@ -56,15 +70,21 @@ Inside a CRUD template, a route can be generated by using the ``Admin`` class.
 
     <a href="{{ admin.generateUrl('list', params|merge('page': 1) }}">List</a>
 
+Note that you do not need to provide the Admin's route prefix (baseRouteName) to 
+generate the URL, just the action name.
+
+
 Create a route
 --------------
 
-You can easily register new routes by defining them in the ``Admin`` class.
-Only Admin routes should be registered this way. Of course this requires the
-related action to be defined in the controller.
+You can register new routes by defining them in your ``Admin`` class. Only Admin 
+routes should be registered this way. Of course this requires the related action 
+to be defined in the controller.
 
-As route is always generated with the ``Admin`` context, it can only be
-defined by its name.
+The routes you define in this way are generated within your Admin's context, and
+the only required parameter to ``add()`` is the action name. The second parameter
+can be used to define the URL format to append to ``baseRoutePattern``, if not set
+explicitly this defaults to the action name.
 
 .. code-block:: php
 
@@ -83,7 +103,33 @@ defined by its name.
 Removing a route
 --------------
 
-Any registered route can be easily removed.
+Extending ``Sonata\AdminBundle\Admin\Admin`` will give your Admin classes the following
+default routes:
+    
+* batch
+* create
+* delete
+* export
+* edit
+* list
+* show
+
+You can view all of the current routes defined for an Admin class by using the console to run 
+
+``php app/console sonata:admin:explain <<admin.service.name>>``
+
+for example if your Admin is called sonata.admin.foo you would run 
+
+``php app/console sonata:admin:explain sonata.admin.foo``
+
+Sonata internally checks for the existence of a route before linking to it. As a result, removing a
+route will prevent links to that action from appearing in the administrative interface. For example,
+removing the 'create' route will prevent any links to "Add new" from appearing.
+
+Removing a single route
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Any single registered route can be easily removed by name:
 
 .. code-block:: php
 
@@ -99,8 +145,11 @@ Any registered route can be easily removed.
     }
 
 
-If you want to disable all default Sonata routes except few whitelisted ones, you can use ``clearExcept()`` method.
-This method accepts an array of routes you want to keep active.
+Removing all routes except named ones
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you want to disable all default Sonata routes except few whitelisted ones, you can use 
+the ``clearExcept()`` method. This method accepts an array of routes you want to keep active.
 
 .. code-block:: php
 
@@ -116,6 +165,9 @@ This method accepts an array of routes you want to keep active.
         }
     }
 
+Removing all routes
+^^^^^^^^^^^^^^^^^^^
+
 If you want to remove all default routes, you can use ``clear()`` method.
 
 .. code-block:: php
@@ -132,6 +184,9 @@ If you want to remove all default routes, you can use ``clear()`` method.
         }
     }
 
+Removing routes only when an Admin is embedded
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 To prevent some routes from being available when one Admin is embedded inside another one
 (e.g. to remove the "add new" option when you embed ``TagAdmin`` within ``PostAdmin``) you 
 can use ``hasParentFieldDescription()`` to detect this case and remove the routes.
@@ -151,7 +206,6 @@ can use ``hasParentFieldDescription()`` to detect this case and remove the route
         }
     }
 
-
 Persistent parameters
 ---------------------
 
@@ -178,14 +232,15 @@ method. This method will be used when a link is being generated.
         }
     }
 
-    // the result :
-    //   $admin->generateUrl('create') => /admin/module/create?context=default
+    // the result:
+    // $admin->generateUrl('create') => /admin/module/create?context=default
 
-Default route in List Action
-----------------------------
+Changing the default route in a List Action
+-------------------------------------------
 
-Sometimes you need show entity without edit. You can choose route in addIdentifier method
-of ListMapper
+Usually the identifier column of a list action links to the edit screen. To change the 
+list action's links to point to a different action, set the ``route`` option in your call to
+``ListMapper::addIdentifier()``. For example, to link to show instead of edit:
 
 .. code-block:: php
 
@@ -195,6 +250,8 @@ of ListMapper
         public function configureListFields(ListMapper $listMapper)
         {
             $listMapper
-                ->addIdentifier('name', null, array('label' => 'name', 'route' => array('name' => 'show')));
+                ->addIdentifier('name', null, array(
+                    'route' => array('name' => 'show')
+                ));
         }
     }