[WCM] Updated tutorial for new routing auto bundle

cookbook/creating_a_cms/auto-routing.rst

@@ -1,7 +1,7 @@
 Routing and Automatic Routing
 -----------------------------
 
-The routes (URLs) to your content will be automatically created and updated
+The routes (URIs) to your content will be automatically created and updated
 using the RoutingAutoBundle. This bundle uses a configuration language to
 specify automatic creation of routes, which can be a bit hard to grasp the
 first time you see it.
@@ -17,7 +17,7 @@ new route will be linked back to the target content:
 
 The paths above represent the path in the PHPCR-ODM document tree. In the next
 section you will define ``/cms/routes`` as the base path for routes, and subsequently
-the contents will be available at the following URLs:
+the contents will be available at the following URIs:
 
 * **Home**: ``http://localhost:8000/page/home``
 * **About**: ``http://localhost:8000/page/about``
@@ -26,22 +26,8 @@ the contents will be available at the following URLs:
 Installation
 ~~~~~~~~~~~~
 
-Ensure that you have the following package installed:
-
-.. code-block:: javascript
-
-    {
-        ...
-        require: {
-            ...
-            "symfony-cmf/routing-auto-bundle": "1.0.*@alpha"
-        },
-        ...
-    }
-
-.. note::
-
-    You are installing the bleeding edge version of the routing-auto bundle.
+Ensure that you installed the RoutingAutoBundle package as detailed in the :ref:`gettingstarted_installadditionbundles`
+section.
 
 Enable the routing bundles to your kernel::
 
@@ -135,88 +121,53 @@ This will:
 Auto Routing Configuration
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Create the following file in your applications configuration directory:
+First you need to configure the auto routing bundle:
 
 .. code-block:: yaml
 
-    # app/config/routing_auto.yml
     cmf_routing_auto:
-        mappings:
-            Acme\BasicCmsBundle\Document\Page:
-                content_path:
-                    pages:
-                        provider: [specified, { path: /cms/routes/page }]
-                        exists_action: use
-                        not_exists_action: create
-                content_name:
-                    provider: [content_method, { method: getTitle }]
-                    exists_action: auto_increment
-                    not_exists_action: create
-
-            Acme\BasicCmsBundle\Document\Post:
-                content_path:
-                    blog_path:
-                        provider: [specified, { path: /cms/routes/post }]
-                        exists_action: use
-                        not_exists_action: create
-                    date:
-                        provider: [content_datetime, { method: getDate}]
-                        exists_action: use
-                        not_exists_action: create
-                content_name:
-                    provider: [content_method, { method: getTitle }]
-                    exists_action: auto_increment
-                    not_exists_action: create
+        persistence:
+            phpcr:
+                enabled: true
 
-This will configure the routing auto system to automatically create and update
-route documents for both the ``Page`` and ``Post`` documents. 
+The above configures the RoutingAutoBundle to work with PHPCR-ODM.
 
-In summary:
+You can now proceed to mapping your documents, create the following in your
+*bundles* configuration directory:
 
-* The ``content_path`` key represents the parent path of the content, e.g.
-  ``/if/this/is/a/path`` then the ``content_path``
-  represents ``/if/this/is/a``;
-* Each element under ``content_path`` represents a section of the URL;
-* The first element ``blog_path`` uses a *provider* which *specifies* a
-  path. If that path exists then it will do nothing;
-* The second element uses the ``content_datetime`` provider, which will
-  use a ``DateTime`` object returned from the specified method on the
-  content object (the ``Post``) and create a path from it, e.g.
-  ``2013/10/13``;
-* The ``content_name`` key represents the last part of the path, e.g. ``path``
-  from ``/if/this/is/a/path``.
+.. code-block:: yaml
 
-Now you will need to include this configuration:
+    # src/Acme/BasicCmsBundle/Resources/config/cmf_routing_auto.yml
+    Acme\BasicCmsBundle\Document\Page:
+        uri_schema: /page/{title}
+        token_providers:
+            title: [content_method, { method: getTitle } ]
 
-.. configuration-block::
-
-    .. code-block:: yaml
+    Acme\BasicCmsBundle\Document\Post:
+        uri_schema: /post/{date}/{title}
+        token_providers:
+            date: [content_datetime, { method: getDate }
+            title: [content_method, { method: getTitle }]
 
-        # app/config/config.yml
-        imports:
-            - { resource: routing_auto.yml }
+.. note::
 
-    .. code-block:: xml
+    RoutingAutoBundle mapping bundles are registered automatically when they are named
+    as above, you may alternatively explicitly declare from where the mappings should be loaded,
+    see the :doc:`../../bundles/routing_auto/index` documentation for more information.
 
-        <!-- src/Acme/BasicCmsBUndle/Resources/config/config.yml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <container 
-            xmlns="http://symfony.com/schema/dic/services" 
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
-            xsi:schemaLocation="http://symfony.com/schema/dic/services 
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
-
-            <import resource="routing_auto.yml"/>
-        </container>
-
-    .. code-block:: php
+This will configure the routing auto system to automatically create and update
+route documents for both the ``Page`` and ``Post`` documents. 
 
-        // src/Acme/BasicCmsBundle/Resources/config/config.php
+In summary, for each class:
 
-        // ...
-        $this->import('routing_auto.yml');
+* We defined a ``uri_schema`` which defines the form of the URI which will be
+  generated.
+  * Within the schema you place ``{tokens}`` - placeholders for values provided by...
+* Token providers provide values which will be substituted into the URI. Here
+  you use two different providers - ``content_date`` and ``content_method``.
+  Both will return dynamic values from the subject object itself.
 
-and reload the fixtures:
+Now reload the fixtures:
 
 .. code-block:: bash
 

cookbook/creating_a_cms/content-to-controllers.rst

@@ -1,7 +1,45 @@
 Controllers and Templates
 -------------------------
 
-Go to the URL http://localhost:8000/page/home in your browser - this should be
+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).
+
+Earlier we did not have the RoutingBundle installed, so we could not add the mapping. 
+
+Map the ``$routes`` property to contain a collection of all the routes which refer to this
+document::
+
+    // src/AcmeBundle/BasicCmsBundle/Document/ContentTrait.php
+
+    // ...
+
+    trait ContentTrait
+    {
+        // ...
+
+        /**
+         * @PHPCR\Referrers(
+         *     referringDocument="Symfony\Cmf\Bundle\RoutingBundle\Doctrine\Phpcr\Route",
+         *     referencedBy="content"
+         * )
+         */
+        protected $routes;
+
+        // ...
+    } 
+
+Now you can call the method ``getRoutes`` on either ``Page`` or ``Post`` and retrieve all the
+routes which refer to that document ... pretty cool!
+
+Route requests to a controller
+..............................
+
+Go to the URL http://127.0.0.1:8000/page/home in your browser - this should be
 your page, but it says that it cannot find a controller. In other words it has
 found the *route referencing the page* for your page but Symfony does not know what
 to do with it.

cookbook/creating_a_cms/getting-started.rst

@@ -4,9 +4,11 @@ Getting Started
 Initializing the Project
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-First, follow the generic steps in :doc:`../../bundles/phpcr_odm/introduction`
+First, follow the generic steps in :doc:`../database/create_new_project_phpcr_odm`
 to create a new project using the PHPCR-ODM.
 
+.. _gettingstarted_installadditionbundles:
+
 Install Additional Bundles
 ..........................
 
@@ -23,19 +25,28 @@ section titled "installation".
 If you intend to complete the entire tutorial you can save some time by adding
 all of the required packages now.
 
+.. note::
+
+    The routing-auto bundle is currently unstable, the package versions listed below are required
+    but are not **stable**. This means that this is a somewhat volatile combination and you should
+    think twice before deploying to production -- there will be a stable release soon.
+
+Please ensure that the packages below replace any packages already defined in your ``composer.json``
+file in the previous step.
+
 .. code-block:: javascript
 
     {
         ...
         require: {
             ...
-            "symfony-cmf/routing-auto-bundle": "1.0.*@alpha",
-            "symfony-cmf/menu-bundle": "1.1.*",
+            "doctrine/phpcr-bundle": "1.0.0",
+            "jackalope/jackalope-doctrine-dbal": "1.1.0",
+            "symfony-cmf/routing-auto-bundle": "dev-master",
+            "symfony-cmf/menu-bundle": "1.2.*",
             "sonata-project/doctrine-phpcr-admin-bundle": "1.1.*",
-            "symfony-cmf/tree-browser-bundle": "1.1.*",
+            "symfony-cmf/tree-browser-bundle": "1.1.x-dev as 1.0",
             "doctrine/data-fixtures": "1.0.*",
-
-            "doctrine/phpcr-odm": "1.1.*",
             "phpcr/phpcr-utils": "1.1.*",
             "doctrine/phpcr-bundle": "1.1.*",
             "symfony-cmf/routing-bundle": "1.2.*",
@@ -110,7 +121,7 @@ to reduce code duplication::
         protected $parent;
 
         /**
-         * @PHPCR\NodeName()
+         * @PHPCR\Nodename()
          */
         protected $title;
 
@@ -119,12 +130,6 @@ to reduce code duplication::
          */
         protected $content;
 
-        /**
-         * @PHPCR\Referrers(
-         *     referringDocument="Symfony\Cmf\Bundle\RoutingBundle\Doctrine\Phpcr\Route",
-         *     referencedBy="content"
-         * )
-         */
         protected $routes;
 
         public function getId()
@@ -267,8 +272,8 @@ configuration:
 
     .. code-block:: xml
 
-        <!-- src/Acme\BasicCmsBundle\Resources\services.xml -->
         <?xml version="1.0" encoding="UTF-8" ?>
+        <!-- src/Acme\BasicCmsBundle\Resources\services.xml -->
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:acme_demo="http://www.example.com/symfony/schema/"
@@ -415,6 +420,8 @@ and add some posts::
         }
     }
 
+The 
+
 and load the fixtures:
 
 .. code-block:: bash

cookbook/creating_a_cms/make-homepage.rst

@@ -51,6 +51,11 @@ Create the site document::
         {
             $this->homepage = $homepage;
         }
+
+        public function setId($id)
+        {
+            $this->id = $id;
+        }
     }
 
 Initializing the Site Document
@@ -85,6 +90,7 @@ node::
     use Doctrine\Bundle\PHPCRBundle\Initializer\InitializerInterface;
     use PHPCR\Util\NodeHelper;
     use Doctrine\Bundle\PHPCRBundle\ManagerRegistry;
+    use Acme\BasicCmsBundle\Document\Site;
 
     class SiteInitializer implements InitializerInterface
     {
@@ -102,7 +108,7 @@ node::
                 return;
             }
 
-            $site = new Acme\BasicCmsBundle\Document\Site();
+            $site = new Site();
             $site->setId($this->basePath);
             $dm->persist($site);
             $dm->flush();
@@ -178,12 +184,13 @@ follows:
             ->addTag('doctrine_phpcr.initializer', array('name' => 'doctrine_phpcr.initializer')
         ;
 
-Now empty your repository and then reinitialize it:
+Now empty your repository, reinitialize it and reload your fixtures:
 
 .. code-block:: bash
 
     $ php app/console doctrine:phpcr:node:remove /cms
     $ php app/console doctrine:phpcr:repository:init
+    $ php app/console doctrine:phpcr:fixtures:load
 
 and verify that the ``cms`` node has been created correctly, using the
 ``doctrine:phpcr:node:dump`` command with the ``props`` flag: