Moved tutorial to its own section

wouterj · wouterj · commit 6f21e4bf4e09 · 2014-08-25T11:47:06.000+02:00
diff --git a/cookbook/index.rst b/cookbook/index.rst
@@ -4,7 +4,6 @@ The Cookbook
 .. toctree::
     :hidden:
 
-    creating_a_cms/index
     database/choosing_storage_layer
     database/choosing_phpcr_implementation
     database/running_jackrabbit
diff --git a/cookbook/map.rst.inc b/cookbook/map.rst.inc
@@ -11,5 +11,3 @@
   * :doc:`Installing the CMF Standard Edition <../book/installation>` (in the book)
   * :doc:`editions/cmf_sandbox`
   * :doc:`editions/cmf_core`
-
-* :doc:`creating_a_cms/index`
diff --git a/index.rst b/index.rst
@@ -22,6 +22,7 @@ implementing the philosophy of the `decoupled CMS`_.
     contributing/index
     reference/index
     cookbook/index
+    tutorial/index
 
 Quick Tour
 ----------
@@ -54,6 +55,24 @@ will typically want to keep this close at hand.
     book/static_content
     book/structuring_content
 
+Tutorial
+--------
+
+The tutorial guides you through all features of the CMF. It uses a step-by-step
+way to create a complete website build from the ground up with the CMF.
+
+.. toctree::
+    :maxdepth: 1
+
+    tutorial/introduction
+    tutorial/getting-started
+    tutorial/auto-routing
+    tutorial/sonata-admin
+    tutorial/content-to-controllers
+    tutorial/the-frontend
+    tutorial/make-homepage
+    tutorial/conclusion
+
 Bundles
 -------
 
diff --git a/tutorial/auto-routing.rst b/tutorial/auto-routing.rst
@@ -1,19 +1,19 @@
 Routing and Automatic Routing
------------------------------
+=============================
 
 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.
 
 For a full explanation refer to the
-:doc:`../../bundles/routing_auto/index`.
+:doc:`RoutingAutoBundle <../bundles/routing_auto/introduction>`.
 
 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
 new route will be linked back to the target content:
 
-.. image:: ../../_images/cookbook/basic-cms-objects.png
+.. image:: ../_images/cookbook/basic-cms-objects.png
 
 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
@@ -24,10 +24,10 @@ the contents will be available at the following URIs:
 * etc.
 
 Installation
-~~~~~~~~~~~~
+------------
 
-Ensure that you installed the RoutingAutoBundle package as detailed in the :ref:`gettingstarted_installadditionbundles`
-section.
+Ensure that you installed the RoutingAutoBundle package as detailed in the
+:ref:`gettingstarted_installadditionbundles` section.
 
 Enable the routing bundles to your kernel::
 
@@ -51,7 +51,7 @@ Enable the routing bundles to your kernel::
     `symfony-cmf/routing-auto-bundle` depends on it.
 
 Enable the Dynamic Router
-~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------
 
 The RoutingAutoBundle uses the CMF `RoutingBundle`_ which enables routes to
 be provided from a database (in addition to being provided from
@@ -119,41 +119,91 @@ This will:
    can be found at ``/cms/routes``.
 
 Auto Routing Configuration
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------
 
 First you need to configure the auto routing bundle:
 
-.. code-block:: yaml
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/config.yml
+        cmf_routing_auto:
+            persistence:
+                phpcr:
+                    enabled: true
+
+    .. code-block:: xml
+
+        <!-- app/config/config.xml -->
+        <container xmlns="http://symfony.com/schema/dic/services">
+            <config xmlns="http://cmf.symfony.com/schema/dic/routing_auto">
+                <persistence>
+                    <phpcr />
+                </persistence>
+            </config>
+       </container>
+
+    .. code-block:: php
+
+        // app/config/config.php
+        $container->loadFromExtension('cmf_routing_auto', array(
+            'persistence' => array(
+                'phpcr' => array(
+                    'enabled' => true,
+                ),
+            ),
+        ));
 
-    cmf_routing_auto:
-        persistence:
-            phpcr:
-                enabled: true
 
 The above configures the RoutingAutoBundle to work with PHPCR-ODM.
 
 You can now proceed to mapping your documents, create the following in your
 *bundles* configuration directory:
 
-.. code-block:: yaml
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # src/Acme/BasicCmsBundle/Resources/config/cmf_routing_auto.yml
+        Acme\BasicCmsBundle\Document\Page:
+            uri_schema: /page/{title}
+            token_providers:
+                title: [content_method, { method: getTitle }]
+
+        Acme\BasicCmsBundle\Document\Post:
+            uri_schema: /post/{date}/{title}
+            token_providers:
+                date: [content_datetime, { method: getDate }]
+                title: [content_method, { method: getTitle }]
+
+    .. code-block:: xml
+
+        <!-- src/Acme/BasicCmsBundle/Resources/config/cmf_routing_auto.xml -->
+        <auto-mapping xmlns="http://cmf.symfony.com/schema/routing_auto">
+            <mapping class="Acme\BasicCmsBundle\Document\Page"
+                uri-schema="/page/{title}">
+
+                <token-provider token="title" name="content_method">
+                    <option name="method">getTitle</option>
+                </token-provider>
+            </mapping>
 
-    # src/Acme/BasicCmsBundle/Resources/config/cmf_routing_auto.yml
-    Acme\BasicCmsBundle\Document\Page:
-        uri_schema: /page/{title}
-        token_providers:
-            title: [content_method, { method: getTitle } ]
+            <mapping class="Acme\BasicCmsBundle\Document\Post"
+                extends="Acme\BasicCmsBundle\Document\Page"
+                uri-schema="/post/{date}/{title}">
 
-    Acme\BasicCmsBundle\Document\Post:
-        uri_schema: /post/{date}/{title}
-        token_providers:
-            date: [content_datetime, { method: getDate }
-            title: [content_method, { method: getTitle }]
+                <token-provider token="date" name="content_datetime">
+                    <option name="method">getDate</option>
+                </token-provider>
+            </mapping>
+        </auto-mapping>
 
 .. note::
 
     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.
+    see the :doc:`../bundles/routing_auto/introduction` documentation for more information.
 
 This will configure the routing auto system to automatically create and update
 route documents for both the ``Page`` and ``Post`` documents. 
diff --git a/tutorial/conclusion.rst b/tutorial/conclusion.rst
@@ -1,5 +1,5 @@
 Conclusion
-----------
+==========
 
 And thats it! Well done. You have created a very minimum but functional
 CMS which can act as a good foundation for larger projects!
diff --git a/tutorial/content-to-controllers.rst b/tutorial/content-to-controllers.rst
@@ -1,23 +1,22 @@
 Controllers and Templates
--------------------------
+=========================
 
 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
+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. 
+Earlier you did not have the RoutingBundle installed, so you 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
     {
         // ...
@@ -36,8 +35,8 @@ document::
 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
-..............................
+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
diff --git a/tutorial/getting-started.rst b/tutorial/getting-started.rst
@@ -1,16 +1,16 @@
 Getting Started
----------------
+===============
 
 Initializing the Project
-~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------
 
-First, follow the generic steps in :doc:`../database/create_new_project_phpcr_odm`
+First, follow the generic steps in :doc:`../cookbook/database/create_new_project_phpcr_odm`
 to create a new project using the PHPCR-ODM.
 
 .. _gettingstarted_installadditionbundles:
 
 Install Additional Bundles
-..........................
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The complete tutorial requires the following packages:
 
@@ -59,12 +59,11 @@ Note that each time you modify your ``composer.json`` file you are required to
 run ``composer update``.
 
 Initialize the Database
-.......................
+~~~~~~~~~~~~~~~~~~~~~~~
 
-If you have followed the main instructions in
-:doc:`../../bundles/phpcr_odm/introduction` then you are using the
-`Doctrine DBAL Jackalope`_ PHPCR backend with MySQL and you will need to
-create the database:
+If you have followed the main instructions in :doc:`../bundles/phpcr_odm/introduction`
+then you are using the `Doctrine DBAL Jackalope`_ PHPCR backend with MySQL and
+you will need to create the database:
 
 .. code-block:: bash
 
@@ -318,7 +317,7 @@ configuration:
     The initializers operate at the PHPCR level, not the PHPCR-ODM level - this
     means that you are dealing with nodes and not documents. You do not have
     to understand these details right now. To learn more about PHPCR read
-    :doc:`../database/choosing_storage_layer`.
+    :doc:`../cookbook/database/choosing_storage_layer`.
 
 The initalizers will be executed automatically when you load your data
 fixtures (as detailed in the next section) or alternatively you can execute
diff --git a/tutorial/index.rst b/tutorial/index.rst
diff --git a/tutorial/introduction.rst b/tutorial/introduction.rst
@@ -8,9 +8,9 @@ Creating a Basic CMS using the RoutingAutoBundle
 This series of articles will show you how to create a basic CMS from scratch
 using the following bundles:
 
-* :doc:`../../bundles/routing_auto/index`;
-* :doc:`../../bundles/phpcr_odm/index`;
-* :doc:`../../bundles/menu/index`;
+* :doc:`../bundles/routing_auto/introduction`;
+* :doc:`../bundles/phpcr_odm/introduction`;
+* :doc:`../bundles/menu/introduction`;
 * SonataDoctrinePHPCRAdminBundle_.
 
 It is assumed that you have:
@@ -28,11 +28,11 @@ The auto routing integration will automatically create and update the routes
 post content documents. In addition each page content document will double up
 as a menu item.
 
-.. image:: ../../_images/cookbook/basic-cms-intro-sketch.png
+.. image:: ../_images/cookbook/basic-cms-intro-sketch.png
 
 .. note::
 
-    There exists a bundle called :doc:`../../bundles/simple_cms/index` which
+    There exists a bundle called :doc:`../bundles/simple_cms/index` which
     provides a similar solution to the one proposed in this tutorial. It
     combines the route, menu and content into a single document and uses a
     custom router. The approach taken in this tutorial will combine only the menu
diff --git a/tutorial/make-homepage.rst b/tutorial/make-homepage.rst
@@ -1,5 +1,5 @@
 The Site Document and the Homepage
-----------------------------------
+==================================
 
 All of your content should now be available at various URLs but your homepage
 (http://localhost:8000) still shows the default Symfony Standard Edition
@@ -11,10 +11,10 @@ allows the user to mark a ``Page`` to act as the homepage of your CMS.
 .. note::
 
     This is just one of many strategies for routing the homepage. For example,
-    another option would be put a `RedirectRoute` document at `/cms/routes`.
+    another option would be put a ``RedirectRoute`` document at ``/cms/routes``.
 
 Storing the Data
-~~~~~~~~~~~~~~~~
+----------------
 
 You need a document which can store data about your CMS - this will be known
 as the site document and it will contain a reference to the ``Page`` document
@@ -59,7 +59,7 @@ Create the site document::
     }
 
 Initializing the Site Document
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------
 
 Where does the ``Site`` document belong? The document hierarchy currently
 looks like this:
@@ -220,7 +220,7 @@ and verify that the ``cms`` node has been created correctly, using the
     initialization choices take place - do whatever you prefer.
 
 Create the Make Homepage Button
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------
 
 You will need a way to allow the administrator of your site to select which
 page should act as the homepage. You will modify the ``PageAdmin`` class so
@@ -313,10 +313,10 @@ that it knows the edit page is requested, it retrieves the *subject* from the ad
 class which is the ``Page`` currently being edited, it then adds a menu item to
 the menu.
 
-.. image:: ../../_images/cookbook/basic-cms-sonata-admin-make-homepage.png
+.. image:: ../_images/cookbook/basic-cms-sonata-admin-make-homepage.png
 
 Routing the Homepage
-~~~~~~~~~~~~~~~~~~~~
+--------------------
 
 Now that you have enabled the administrator to designate a page to be used as
 a homepage you need to actually make the CMS use this information to render
diff --git a/tutorial/sonata-admin.rst b/tutorial/sonata-admin.rst
diff --git a/tutorial/the-frontend.rst b/tutorial/the-frontend.rst
