Updated style and contents

Author: dantleech

cookbook/using-a-custom-route-repository.rst

@@ -1,12 +1,20 @@
 Using a custom route repository with Dynmaic Router
 ===================================================
 
-The Dynamic Router allows you to customize the route Repository (i.e. the class responsible for retrieving routes from the database), and by extension, the Route objects.
+The Dynamic Router allows you to customize the route Repository (i.e. the class 
+responsible for retrieving routes from the database), and by extension, the 
+Route objects.
 
 Creating the route repository
 -----------------------------
 
-The route repository must implement the `RouteRepositoryInterface` and in addition should return objects which extend the Symfony Route class. The following class provides a simple solution which uses an ODM Repository, but you can equally imagine an ORM repository or indeed anything you like, as long as it implements the interface.
+The route repository must implement the `RouteRepositoryInterface` and in 
+addition should return instances of the Symfony Route class. The 
+following class provides a simple solution using an ODM Repository. For the
+purpose of example we create the Symfony Route object and map the pattern
+to it directly.
+
+Why return multiple routes? .. @todo explain that here.
 
 .. code-block:: php
 
@@ -16,15 +24,20 @@ The route repository must implement the `RouteRepositoryInterface` and in additi
     use Doctrine\ODM\PHPCR\DocumentRepository;
     use Symfony\Cmf\Component\Routing\RouteRepositoryInterface;
     use Symfony\Component\Routing\RouteCollection;
+    use Symfony\Component\Routing\Route as SymfonyRoute;
 
     class RouteRepository extends DocumentRepository implements RouteRepositoryInterface
 
     {
         public function findManyByUrl($url)
         {
-            $route = $this->findOneBy(array(
+            $myDocument = $this->findOneBy(array(
                 'path' => $url,
             ));
+
+            $pattern = $myDocument->getUrl(); // e.g. "/this/is/a/route"
+
+            $route = new SymfonyRoute($pattern);
             $collection = new RouteCollection(array($route));
 
             return $collection;
@@ -43,8 +56,9 @@ The route repository must implement the `RouteRepositoryInterface` and in additi
 The route class
 ---------------
 
-As noted above, the route classes provided by the route repository must  *extend* `Symfony\Component\Routing\Route` and provide whatever other parameters required by the storage engine, the following is an example ODM object:
-
+As noted above, the route classes provided by the route repository must  
+be instances of `Symfony\Component\Routing\Route`. A good pattern is to
+have your ODM/ORM/Other Document extend the Symfony Route class.
 
 .. code-block:: php
 
@@ -53,20 +67,21 @@ As noted above, the route classes provided by the route repository must  *extend
     namespace MyVendor\Bundle\MyBundle\Document;
     use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCR;
     use DCMS\Bundle\CoreBundle\Validation\Constraints as RoutingValidation;
-    use Symfony\Component\Routing\Route as BaseRoute;
+    use Symfony\Component\Routing\Route as SymfonyRoute;
 
     /**
      * @PHPCR\Document(repositoryClass="MyVendor\Bundle\MyBundle\Repository\RouteRepository")
      */
-    class Route extends BaseRoute
+    class Route extends SymfonyRoute
     {
         // @todo: Fill this out
     }
 
 Replacing the default CMF repository
 ------------------------------------
 
-The final step is to replace the default CMF routing repository service with your own. This is easily accomplished using the application configuration:
+The final step is to replace the default CMF routing repository service with 
+your own. This is easily accomplished using the application configuration:
 
 .. code-block:: yaml
 
@@ -76,4 +91,6 @@ The final step is to replace the default CMF routing repository service with you
             enabled: true
             route_repository_service_id: my_bundle.repository.endpoint
    
-Where `my_bundle.repository.endpoint` is the service ID of your repository. See `Creating and configuring services in the container <http://symfony.com/doc/current/book/service_container.html#creating-configuring-services-in-the-container/>`_ for information on creating custom services.
+Where `my_bundle.repository.endpoint` is the service ID of your repository. 
+See `Creating and configuring services in the container <http://symfony.com/doc/current/book/service_container.html#creating-configuring-services-in-the-container/>`_ 
+for information on creating custom services.

index.rst

@@ -55,6 +55,7 @@ Special solutions for special needs that go beyond standard usage.
 	:maxdepth: 1
 
 	cookbook/phpcr-odm-custom-documentclass-mapper
+	cookbook/using-a-custom-route-repository
 
 Components
 ----------