updated the Quick Tour for PR3 (WIP)

symfony · Aug 6, 2010 · 5af332b · 5af332b
1 parent 325d45a
commit 5af332b
Show file tree

Hide file tree

Showing 4 changed files with 138 additions and 36 deletions.
diff --git a/quick_tour/the_architecture.rst b/quick_tour/the_architecture.rst
@@ -32,7 +32,7 @@ live:
 
 .. code-block:: html+php
 
-    # web/index.php
+    <!-- web/index.php -->
     <?php
 
     require_once __DIR__.'/../hello/HelloKernel.php';
@@ -66,8 +66,6 @@ This class must implement five methods:
 * ``registerContainerConfiguration()``: Returns the main configuration object
   (more on this later);
 
-* ``registerRoutes()``: Returns the routing configuration.
-
 Have a look at the default implementation of these methods to better
 understand the flexibility of the framework. At the beginning of this
 tutorial, you opened the ``hello/config/routing.yml`` file. The path is

diff --git a/quick_tour/the_big_picture.rst b/quick_tour/the_big_picture.rst
@@ -94,15 +94,49 @@ Routing
 But how does Symfony route the request to your code? Simply by reading the
 routing configuration file:
 
-.. code-block:: yaml
+.. configuration-block::
 
-    # hello/config/routing.yml
-    homepage:
-        pattern:  /
-        defaults: { _controller: FoundationBundle:Default:index }
+    .. code-block:: yaml
 
-    hello:
-        resource: HelloBundle/Resources/config/routing.yml
+        # hello/config/routing.yml
+        homepage:
+            pattern:  /
+            defaults: { _controller: FoundationBundle:Default:index }
+
+        hello:
+            resource: HelloBundle/Resources/config/routing.yml
+
+    .. code-block:: xml
+
+        <!-- hello/config/routing.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+
+        <routes xmlns="http://www.symfony-project.org/schema/routing"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://www.symfony-project.org/schema/routing http://www.symfony-project.org/schema/routing/routing-1.0.xsd">
+
+            <route id="homepage" pattern="/">
+                <default key="_controller">FoundationBundle:Default:index</default>
+            </route>
+
+            <import resource="HelloBundle/Resources/config/routing.xml" />
+        </routes>
+
+    .. code-block:: php
+
+        // hello/config/routing.php
+        use Symfony\Components\Routing\RouteCollection;
+        use Symfony\Components\Routing\Route;
+
+        $collection = new RouteCollection();
+
+        $collection->addRoute('homepage', new Route('/', array(
+            '_controller' => 'FoundationBundle:Default:index',
+        )));
+
+        $collection->import('HelloBundle/Resources/config/routing.php');
+
+        return $collection;
 
 The file is written in `YAML`, a simple format that makes the description of
 configuration settings very easy. All the configuration files in Symfony can
@@ -114,12 +148,41 @@ The first three lines of the routing configuration file define which code to
 call when the user requests the "``/``" resource. More interesting is the last
 line, which imports another routing configuration file that reads as follows:
 
-.. code-block:: yaml
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # src/Application/HelloBundle/Resources/config/routing.yml
+        hello:
+            pattern:  /hello/:name
+            defaults: { _controller: HelloBundle:Hello:index }
+
+    .. code-block:: xml
+
+        <!-- src/Application/HelloBundle/Resources/config/routing.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+
+        <routes xmlns="http://www.symfony-project.org/schema/routing"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://www.symfony-project.org/schema/routing http://www.symfony-project.org/schema/routing/routing-1.0.xsd">
+
+            <route id="hello" pattern="/hello/:name">
+                <default key="_controller">HelloBundle:Hello:index</default>
+            </route>
+        </routes>
+
+    .. code-block:: php
+
+        // src/Application/HelloBundle/Resources/config/routing.php
+        use Symfony\Components\Routing\RouteCollection;
+        use Symfony\Components\Routing\Route;
+
+        $collection = new RouteCollection();
+        $collection->addRoute('hello', new Route('/hello/:name', array(
+            '_controller' => 'HelloBundle:Hello:index',
+        )));
 
-    # src/Application/HelloBundle/Resources/config/routing.yml
-    hello:
-        pattern:  /hello/:name
-        defaults: { _controller: HelloBundle:Hello:index }
+        return $collection;
 
 Here we go! As you can see, the "``/hello/:name``" resource pattern (a string
 beginning with a colon like ``:name`` is a placeholder) is mapped to a

diff --git a/quick_tour/the_controller.rst b/quick_tour/the_controller.rst
@@ -23,12 +23,30 @@ there are plenty of different formats to choose from. Supporting those formats
 in Symfony is straightforward. Edit ``routing.yml`` and add a ``_format`` with a
 value of ``xml``:
 
-.. code-block:: yaml
+.. configuration-block::
 
-    # src/Application/HelloBundle/Resources/config/routing.yml
-    hello:
-        pattern:  /hello/:name
-        defaults: { _controller: HelloBundle:Hello:index, _format: xml }
+    .. code-block:: yaml
+
+        # src/Application/HelloBundle/Resources/config/routing.yml
+        hello:
+            pattern:  /hello/:name
+            defaults: { _controller: HelloBundle:Hello:index, _format: xml }
+
+    .. code-block:: xml
+
+        <!-- src/Application/HelloBundle/Resources/config/routing.xml -->
+        <route id="hello" pattern="/hello/:name">
+            <default key="_controller">HelloBundle:Hello:index</default>
+            <default key="_format">xml</default>
+        </route>
+
+    .. code-block:: php
+
+        // src/Application/HelloBundle/Resources/config/routing.php
+        $collection->addRoute('hello', new Route('/hello/:name', array(
+            '_controller' => 'HelloBundle:Hello:index',
+            '_format'     => 'xml',
+        )));
 
 Then, add an ``index.xml.php`` template along side ``index.php``:
 
@@ -44,13 +62,34 @@ formats, Symfony will also automatically choose the best ``Content-Type`` header
 for the response. If you want to support different formats for a single
 action, use the ``:_format`` placeholder in the pattern instead:
 
-.. code-block:: yaml
+.. configuration-block::
+
+    .. code-block:: yaml
 
-    # src/Application/HelloBundle/Resources/config/routing.yml
-    hello:
-        pattern:      /hello/:name.:_format
-        defaults:     { _controller: HelloBundle:Hello:index, _format: html }
-        requirements: { _format: (html|xml|json) }
+        # src/Application/HelloBundle/Resources/config/routing.yml
+        hello:
+            pattern:      /hello/:name.:_format
+            defaults:     { _controller: HelloBundle:Hello:index, _format: html }
+            requirements: { _format: (html|xml|json) }
+
+    .. code-block:: xml
+
+        <!-- src/Application/HelloBundle/Resources/config/routing.xml -->
+        <route id="hello" pattern="/hello/:name.:_format">
+            <default key="_controller">HelloBundle:Hello:index</default>
+            <default key="_format">html</default>
+            <requirement key="_format">(html|xml|json)</requirement>
+        </route>
+
+    .. code-block:: php
+
+        // src/Application/HelloBundle/Resources/config/routing.php
+        $collection->addRoute('hello', new Route('/hello/:name.:_format', array(
+            '_controller' => 'HelloBundle:Hello:index',
+            '_format'     => 'html',
+        ), array(
+            '_format' => '(html|xml|json)',
+        )));
 
 The controller will now be called for URLs like ``/hello/Fabien.xml`` or
 ``/hello/Fabien.json``. As the default value for ``_format`` is ``html``, the
@@ -187,10 +226,12 @@ by using the native PHP sessions.
 This feature is provided by ``FoundationBundle`` and it can be enabled by adding the
 following line to ``config.yml``:
 
-.. code-block:: yaml
+.. configuration-block::
+
+    .. code-block:: yaml
 
-    # hello/config/config.yml
-    web.user: ~
+        # hello/config/config.yml
+        web.user: ~
 
 Storing and retrieving information from the user can be easily achieved from
 any controller::

diff --git a/quick_tour/the_view.rst b/quick_tour/the_view.rst
@@ -32,7 +32,7 @@ The ``index`` template is decorated by ``layout.php``, thanks to the
 
 .. code-block:: html+php
 
-    # src/Application/HelloBundle/Resources/views/Hello/index.php
+    <!-- src/Application/HelloBundle/Resources/views/Hello/index.php -->
     <?php $view->extend('HelloBundle::layout') ?>
 
     Hello <?php echo $name ?>!
@@ -46,7 +46,7 @@ Now, let's have a look at the ``layout.php`` file:
 
 .. code-block:: html+php
 
-    # src/Application/HelloBundle/Resources/views/layout.php
+    <!-- src/Application/HelloBundle/Resources/views/layout.php -->
     <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
     <html>
         <head>
@@ -81,7 +81,7 @@ decorating the template. In the index template, define a ``title`` slot:
 
 .. code-block:: html+php
 
-    # src/Application/HelloBundle/Resources/views/Hello/index.php
+    <!-- src/Application/HelloBundle/Resources/views/Hello/index.php -->
     <?php $view->extend('HelloBundle::layout') ?>
 
     <?php $view->slots->set('title', 'Hello World app') ?>
@@ -92,7 +92,7 @@ And change the layout to output the title in the header:
 
 .. code-block:: html+php
 
-    # src/Application/HelloBundle/Resources/views/layout.php
+    <!-- src/Application/HelloBundle/Resources/views/layout.php -->
     <html>
         <head>
             <title><?php $view->slots->output('title', 'Default Title') ?></title>
@@ -128,14 +128,14 @@ Create a ``hello.php`` template:
 
 .. code-block:: html+php
 
-    # src/Application/HelloBundle/Resources/views/Hello/hello.php
+    <!-- src/Application/HelloBundle/Resources/views/Hello/hello.php -->
     Hello <?php echo $name ?>!
 
 And change the ``index.php`` template to include it:
 
 .. code-block:: html+php
 
-    # src/Application/HelloBundle/Resources/views/Hello/index.php
+    <!-- src/Application/HelloBundle/Resources/views/Hello/index.php -->
     <?php $view->extend('HelloBundle::layout') ?>
 
     <?php echo $view->render('HelloBundle:Hello:hello', array('name' => $name)) ?>
@@ -158,7 +158,7 @@ template, simply use the following code:
 
 .. code-block:: html+php
 
-    # src/Application/HelloBundle/Resources/views/Hello/index.php
+    <!-- src/Application/HelloBundle/Resources/views/Hello/index.php -->
     <?php $view->actions->output('HelloBundle:Hello:fancy', array('name' => $name, 'color' => 'green')) ?>
 
 Here, the ``HelloBundle:Hello:fancy`` string refers to the ``fancy`` action of the