Updated

dantleech · dantleech · commit b7336e9f338d · 2014-01-11T09:13:10.000Z
diff --git a/cookbook/creating_a_cms/005-introduction.rst b/cookbook/creating_a_cms/005-introduction.rst
@@ -2,15 +2,15 @@
     single: Tutorial, Creating a CMS, RoutingAuto, PHPCR-ODM
     single: MenuBundle, SonataAdmin, SonataDoctrineAdminBundle
 
-Creating a Basic CMS Using the RoutingAutoBundle
+Creating a Basic CMS using the RoutingAutoBundle
 ================================================
 
-This three part article will show you how to create a basic CMS from scratch
+This series of articles will show you how to create a basic CMS from scratch
 using the following bundles:
 
-* :doc:`../bundles/routing_auto`;
-* :doc:`../bundles/phpcr_odm`;
-* :doc:`../bundles/menu/index`;
+* :doc:`../../bundles/routing_auto`;
+* :doc:`../../bundles/phpcr_odm`;
+* :doc:`../../bundles/menu/index`;
 * `SonataDoctrinePhpcrAdminBundle`_.
 
 It is assumed that you have:
diff --git a/cookbook/creating_a_cms/010-getting-started.rst b/cookbook/creating_a_cms/010-getting-started.rst
@@ -4,8 +4,8 @@ Part 1 - Getting Started
 Initializing the Project
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-First, follow the generic steps in :doc:`create_new_project_phpcr_odm` to create a new project using
-the PHPCR-ODM.
+First, follow the generic steps in :doc:`create_new_project_phpcr_odm` to
+create a new project using the PHPCR-ODM.
 
 Install Additional Bundles
 ..........................
@@ -25,7 +25,7 @@ Update ``composer.json`` to require them:
         ...
         require: {
             ...
-            "symfony-cmf/routing-auto-bundle": "dev-master",
+            "symfony-cmf/routing-auto-bundle": "1.0.0@alpha",
             "symfony-cmf/menu-bundle": "1.0",
             "sonata-project/doctrine-phpcr-admin-bundle": "dev-master",
             "doctrine/data-fixtures": "1.0.0"
@@ -62,7 +62,7 @@ database:
     $ mysqladmin create symfony -u root
 
 This will create a new database called ``symfony`` - this is the name used by
-default in the Symfony Standard Edition, change as might be necessary.
+default in the Symfony Standard Edition, change it as might be necessary.
 
 The Doctrine DBAL backend needs to be initialized, the following command
 will create the MySQL schema required to store the hierarchical
@@ -78,6 +78,9 @@ node content of the PHPCR content repository:
     backend and does not require such initialization. It does however require
     the use of Java.
 
+Generate the Bundle
+...................
+
 Now you can generate the bundle in which you will write most of your code:
 
 .. code-block:: bash
@@ -169,7 +172,7 @@ to reduce code duplication::
 
     Traits are only available as of PHP 5.4. If you are running a lesser
     version of PHP you may copy the above code into each class to have the
-    same effect. You may not, however, ``extend`` one class from another, as
+    same effect. You may not, however, ``extend`` one class from the other, as
     this will cause unintended behavior in the admin integration later on.
 
 The ``Page`` class is therefore nice and simple::
@@ -188,11 +191,10 @@ The ``Page`` class is therefore nice and simple::
         use ContentTrait;
     }
 
-Note that the page documet should be ``referenceable``.  This will enable
+Note that the page document should be ``referenceable``. This will enable
 other documents to hold a reference to the page. The ``Post`` class will also
-be referenceable and in addition the ``Post`` class will automatically set the
-date if it has not been explicitly set using the `pre persist lifecycle
-event`_::
+be referenceable and in addition will automatically set the date using the
+`pre persist lifecycle event`_ if it has not been explicitly set previously::
 
     // src/Acme/BasicCms/Document/Post.php
     namespace Acme\BasicCmsBundle\Document;
@@ -227,21 +229,21 @@ event`_::
             return $this->date;
         }
 
-        public function setDate($date)
+        public function setDate(\DateTime $date)
         {
             $this->date = $date;
         }
     }
 
 Both the ``Post`` and ``Page`` classes implement the
-``RouteReferrersReadInterface`` which enables the
-`DynamicRouter to generate URLs`_. (for example with ``{{ path(content) }}``
-in Twig).
+``RouteReferrersReadInterface``. This interface enables the 
+`DynamicRouter to generate URLs`_ from instances of these classes. (for
+example with ``{{ path(content) }}`` in Twig).
 
 Repository Initializer
 ~~~~~~~~~~~~~~~~~~~~~~
 
-`Repository initializers`_ enable you to establish and maintain PHPCR nodes
+:ref:`Repository initializers <../../bundles/phpcr_odm>` enable you to establish and maintain PHPCR nodes
 required by your application, for example you will need the paths
 ``/cms/pages``, ``/cms/posts`` and ``/cms/routes``. The ``GenericInitializer``
 class can be used easily initialize a list of paths. Add the following to your
@@ -255,7 +257,8 @@ service container configuration:
         services:
             acme.basic_cms.phpcr.initializer:
                 class: Doctrine\Bundle\PHPCRBundle\Initializer\GenericInitializer
-                arguments: [ "/cms/pages", "/cms/posts", "/cms/routes" ]
+                arguments: 
+                    - ["/cms/pages", "/cms/posts", "/cms/routes"]
                 tags:
                     - { name: doctrine_phpcr.initializer }
 
@@ -313,8 +316,10 @@ reinitialize) the repository:
 
 .. note::
 
-    This command is an `idempotent`_, which means that it should be safe to run
-    it multiple times, even when you have data in your repository.
+    This command is `idempotent`_, which means that it is safe to run
+    it multiple times, even when you have data in your repository. Note
+    however that it is the responsibility of the initializer to respect
+    idempotency!
 
 Create Data Fixtures
 ~~~~~~~~~~~~~~~~~~~~
@@ -324,20 +329,19 @@ Create a page for your CMS::
     // src/Acme/BasicCmsBundle/DataFixtures/PHPCR/LoadPageData.php
     namespace Acme\BasicCmsBundle\DataFixtures\PHPCR;
 
+    use Acme\BasicCmsBundle\Document\Page;
     use Doctrine\Common\DataFixtures\FixtureInterface;
     use Doctrine\Common\Persistence\ObjectManager;
-    use Acme\BasicCmsBundle\Document\Page;
-    use PHPCR\Util\NodeHelper;
+    use PHPCR\Util\NodeHelpen;
 
     class LoadPageData implements FixtureInterface
     {
         public function load(ObjectManager $dm)
         {
-            NodeHelper::createPath($dm->getPhpcrSession(), '/cms/pages');
             $parent = $dm->find(null, '/cms/pages');
 
             $page = new Page();
-            $page->setTitle('Home');
+            $page->setTitle
             $page->setParent($parent);
             $page->setContent(<<<HERE
     Welcome to the homepage of this really basic CMS.
@@ -363,7 +367,6 @@ and add some posts::
     {
         public function load(ObjectManager $dm)
         {
-            NodeHelper::createPath($dm->getPhpcrSession(), '/cms/posts');
             $parent = $dm->find(null, '/cms/posts');
 
             foreach (array('First', 'Second', 'Third', 'Forth') as $title) {
@@ -390,16 +393,6 @@ and load the fixtures:
 
 You should now have some data in your content repository.
 
-.. note::
-
-    The classes above use ``NodeHelper::createPath`` to create the paths
-    ``/cms/posts`` and ``/cms/pages`` - this is exactly what the
-    initializer did -- why do the classes do it again? This is a known issue - the
-    data fixtures loader will purge the workspace and it will **not** call the
-    initializer, so when using data fixtures it is currently necessary to manually
-    create the paths.
-
-
 .. _`routingautobundle documentation`: http://symfony.com/doc/current/cmf/bundles/routing_auto.html
 .. _`dynamicrouter to generate urls`: http://symfony.com/doc/current/cmf/bundles/routing/dynamic.html#url-generation-with-the-dynamicrouterA
 .. _`idempotent`: http://en.wiktionary.org/wiki/idempotent
diff --git a/cookbook/creating_a_cms/020-auto-routing.rst b/cookbook/creating_a_cms/020-auto-routing.rst
@@ -2,8 +2,12 @@ Part 2: Automatic Routing
 -------------------------
 
 The routes (URLs) to your content will be automatically created and updated
-using the RoutingAutoBundle. This bundle is powerful and somewhat complicated.
-For a full a full explanation refer to the `RoutingAutoBundle documentation`_.
+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.
+
+For a full a full explanation refer to the
+:doc:`../../bundles/routing_auto.rst`_.
 
 In summary, you will configure the auto routing system to create a new auto
 routing document in the routing tree for every post or content created. The
@@ -19,13 +23,12 @@ the contents will be avilable at the following URLs:
 * **About**: ``http://localhost:8000/page/about``
 * etc.
 
-
 Enable the Dynamic Router
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The RoutingAutoBundle uses the CMFs `RoutingBundle`_ which enables routes to
-be provided from a database (as opposed to being provided from
-``routing.[yml|xml|php]`` files for example).
+The RoutingAutoBundle uses the CMF `RoutingBundle`_ which enables routes to
+be provided from a database (in addition to being provided from
+the routing configuration files as in core Symfony 2).
 
 Add the following to your application configuration:
 
@@ -78,12 +81,12 @@ Add the following to your application configuration:
 
 This will:
 
-#. Cause the default Symfony router to be replaced by the chain router.  The
+#. Cause the default Symfony router to be replaced by the chain router. The
    chain router enables you to have multiple routers in your application. You
    add the dynamic router (which can retrieve routes from the database) and
    the default Symfony router (which retrieves routes from configuration
-   files).  The number indicates the order of precedence - the router with the
-   lowest number will be called first.;
+   files). The number indicates the order of precedence - the router with the
+   lowest number will be called first;
 #. Configure the **dynamic** router which you have added to the router chain.
    You specify that it should use the PHPCR backend and that the *root* route
    can be found at ``/cms/routes``.
@@ -177,7 +180,7 @@ Now you will need to include this configuration:
     .. code-block:: xml
 
         <!-- src/Acme/BasicCmsBUndle/Resources/config/config.yml -->
-        ?xml version="1.0" encoding="UTF-8" ?>
+        <?xml version="1.0" encoding="UTF-8" ?>
         <container 
             xmlns="http://symfony.com/schema/dic/services" 
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
diff --git a/cookbook/creating_a_cms/030-sonata-admin.rst b/cookbook/creating_a_cms/030-sonata-admin.rst
@@ -1,7 +1,8 @@
 Part 3 - The Backend
 --------------------
 
-The `SonataAdminBundle`_ bundle will provide our administration interface.
+In this chapter you will build an administration interface with the help
+of the `SonataAdminBundle`_.
 
 Configure Sonata
 ~~~~~~~~~~~~~~~~
@@ -33,13 +34,14 @@ Sonata requires the ``sonata_block`` bundle to be configured in your main config
     .. code-block:: yaml
 
         # app/config/config.yml
+
         # ...
         sonata_block:
             default_contexts: [cms]
             blocks:
                 # Enable the SonataAdminBundle block
                 sonata.admin.block.admin_list:
-                    contexts:   [admin]
+                    contexts: [admin]
 
     .. code-block:: xml
 
@@ -74,6 +76,7 @@ and it requires the following entries in your routing file:
     .. code-block:: yaml
 
         # app/config/routing.yml
+
         admin:
             resource: '@SonataAdminBundle/Resources/config/routing/sonata_admin.xml'
             prefix: /admin
@@ -137,6 +140,8 @@ No translations? Uncomment the translator in the configuration file:
 
     .. code-block:: yaml
 
+        # app/config/config.yml
+
         # ...
         framework:
             # ...
@@ -217,7 +222,7 @@ the RoutingBundle admin as follows:
             ),
         ));
 
-.. note:: 
+.. tip:: 
 
     All Sonata Admin aware CMF bundles have such a configuration option and it
     prevents the admin class (or classes) from being registered.
@@ -295,6 +300,12 @@ to avoid code duplication::
         }
     }
 
+.. note::
+
+    In the ``prePersist`` method of the ``PageAdmin`` you specify always a
+    fixed path, in the future you may want to modify this behavior to
+    enable pages to be structured (for example to have nested menus).
+
 Now you just need to register these classes in the dependency injection
 container configuration:
 
diff --git a/cookbook/creating_a_cms/040-the-frontend.rst b/cookbook/creating_a_cms/040-the-frontend.rst
@@ -57,13 +57,14 @@ You can map a default controller for all instances of ``Page``:
 This will cause requests to be forwarded to this controller when the route
 which matches the incoming request is provided by the dynamic router **and**
 the content document that that route references is of class
-``Acme\BasicCmsBundle\Document\Page``
+``Acme\BasicCmsBundle\Document\Page``.
 
 Now create the action in the default controller - you can pass the ``Page``
 object and all the ``Posts`` to the view::
 
     // src/Acme/BasicCmsBundle/Controller/DefaultController.php
-    //..
+
+    // ...
     class DefaultController extends Controller
     {
         // ...
@@ -77,7 +78,7 @@ object and all the ``Posts`` to the view::
             $posts = $dm->getRepository('Acme\BasicCmsBundle\Document\Post')->findAll();
 
             return array(
-                'page' => $contentDocument,
+                'page'  => $contentDocument,
                 'posts' => $posts,
             );
         }
@@ -106,7 +107,7 @@ Add a corresponding twig template (note that this works because you use the
 
         <!-- src/Acme/BasicCmsBundle/Resources/views/Default/page.html.twig -->
         <h1><?php echo $page->getTitle() ?></h1>
-        <p><?php echo $page->content ?></p>
+        <p><?php echo $page->getContent() ?></p>
         <h2>Our Blog Posts</h2>
         <ul>
             <?php foreach($posts as $post) : ?>
@@ -172,16 +173,16 @@ KnpMenuBundle::
                 'label' => $this->title,
                 'content' => $this,
 
-                'attributes' => array(),
+                'attributes'         => array(),
                 'childrenAttributes' => array(),
-                'displayChildren' => true,
-                'linkAttributes' => array(),
-                'labelAttributes' => array(),
+                'displayChildren'    => true,
+                'linkAttributes'     => array(),
+                'labelAttributes'    => array(),
             );
         }
     }
 
-.. note::
+.. caution::
 
     Don't forget to add the ``Knp\Menu\NodeInterface`` use statement!
 
@@ -267,7 +268,7 @@ applications kernel::
         }
     }
 
-Now you can register the PhpcrMenuProvider from the menu bundle in the service container
+Now you can register the ``PhpcrMenuProvider`` from the menu bundle in the service container
 configuration:
 
 .. configuration-block::
@@ -370,6 +371,7 @@ and finally lets render the menu!
 
         <!-- src/Acme/BasicCmsBundle/Resources/views/Default/page.html.php -->
         
+        <!-- ... -->
         <?php echo $view['knp_menu']->render('main') ?>
 
 Note that ``main`` refers to the name of the root page you added in the data
diff --git a/cookbook/creating_a_cms/050-make-homepage.rst b/cookbook/creating_a_cms/050-make-homepage.rst
diff --git a/cookbook/index.rst b/cookbook/index.rst
