[WIP] Rewrote Templating Docs

components/index.rst

@@ -24,7 +24,7 @@ The Components
     security/index
     serializer
     stopwatch
-    templating
+    templating/index
     yaml/index
 
 .. include:: /components/map.rst.inc

components/map.rst.inc

@@ -102,9 +102,9 @@
   * :doc:`/components/security/authentication`
   * :doc:`/components/security/authorization`
 
-* **Templating**
+* :doc:`/components/templating/index`
 
-  * :doc:`/components/templating`
+  * :doc:`/components/templating/introduction`
 
 * :doc:`/components/yaml/index`
 

components/templating/helpers/assetshelper.rst

@@ -0,0 +1,102 @@
+.. index::
+    single: Templating Helpers; Assets Helper
+
+Assets Helper
+=============
+
+The assets helper's main purpose is to make your application more portable by
+generating assets' paths:
+
+.. code-block:: html+php
+
+   <link href="<?php echo $view['assets']->getUrl('css/style.css') ?>" rel="stylesheet">
+
+   <img src="<?php echo $view['assets']->getUrl('images/logo.png') ?>">
+
+Configure Paths
+---------------
+
+By default, the assets helper will prefix all paths with a slash. You can
+extend this by configuring a basepath in the first argument of the
+constructor::
+
+    use Symfony\Component\Templating\Helper\AssetsHelper;
+
+    // ...
+    $templateEngine->set(new AssetsHelper('/foo/bar'));
+
+Now, if you use the helper everything will be prefixed with ``/foo/bar``:
+
+.. code-block:: html+php
+
+   <img src="<?php echo $view['assets']->getUrl('images/logo.png') ?>">
+   <!-- renders as:
+   <img src="/foo/bar/images/logo.png">
+   -->
+
+Absolute Urls
+-------------
+
+You can also specify a url to use in the second parameter of the constructor::
+
+    // ...
+    $templateEngine->set(new AssetsHelper(null, 'http://cdn.example.com/'));
+
+Now urls are rendered like ``http://cdn.example.com/images/logo.png``.
+
+Versioning
+----------
+
+To avoid using the cached resource after updating the old resource, you can
+use versions which you bump every time you release a new project. The version
+can be specified in the third argument::
+
+    // ...
+    $templateEngine->set(new AssetsHelper(null, null, '328rad75'));
+
+Now, every url is suffixed with ``?328rad75``. If you want to have a different
+format, you can specify the new format in fourth argument. It's a string that
+is used in :phpfunction:`sprintf`. The first argument is the path and the
+second is the version. For instance, ``%s?v=%s`` will be rendered as
+``/images/logo.png?v=328rad75``.
+
+Multiple Packages
+-----------------
+
+Paths are internally handled by packages. The component provides 2 packages by
+default:
+
+* :class:`Symfony\\Component\\Templating\\Asset\\PathPackage`
+* :class:`Symfony\\Component\\Templating\\Asset\\UrlPackage`
+
+You can also have multiple packages::
+
+    // ...
+    $templateEngine->set(new AssetsHelper());
+
+    $templateEngine->get('assets')->addPackage('images', new PathPackage('/images/'));
+    $templateEngine->get('assets')->addPackage('scripts', new PathPackage('/scripts/'));
+
+This will setup the assets helper with 3 packages: the default package which
+defaults to ``/`` (set by the constructor), the images package which prefixes
+it with ``/images/`` and the scripts package which prefixes it with
+``/scripts/``.
+
+If you want to set another default package, you can use
+:method:`Symfony\\Component\\Templating\\Helper\\AssetsHelper::setDefaultPackage`.
+
+You can specify which package you want to use in the second argument of
+:method:`Symfony\\Component\\Templating\\Helper\\AssetsHelper::getUrl`:
+
+.. code-block:: php+html
+
+    <img src="<?php echo $view['assets']->getUrl('foo.png', 'images') ?>">
+    <!-- renders as:
+    <img src="/images/foo.png">
+    -->
+
+Custom Packages
+---------------
+
+You can create your own package by extending
+:class:`Symfony\\Component\\Templating\\Package\\Package`.

components/templating/helpers/index.rst

@@ -0,0 +1,16 @@
+.. index::
+    single: Templating; Templating Helpers
+
+The Templating Helpers
+======================
+
+.. toctree::
+    :hidden:
+
+    slotshelper
+    assetshelper
+
+The Templating Component comes with some useful helpers. These helpers contain
+functions to ease some common tasks.
+
+.. include:: map.rst.inc

components/templating/helpers/map.rst.inc

@@ -0,0 +1,2 @@
+* :doc:`/components/templating/helpers/slotshelper`
+* :doc:`/components/templating/helpers/assetshelper`

components/templating/helpers/slotshelper.rst

@@ -0,0 +1,84 @@
+.. index::
+    single: Templating Helpers; Slots Helper
+
+Slots Helper
+============
+
+More often than not, templates in a project share common elements, like the
+well-known header and footer. The static HTML code can be placed in a layout file
+and the dynamic sections are replaced by slots, which are filled by the child
+template; the layout file decorates the child template.
+
+Displaying Slots
+~~~~~~~~~~~~~~~~
+
+The slots are accessible by using the slots helper (``$view['slots']``). Use
+:method:`Symfony\\Component\\Templating\\Helper\\SlotsHelper::output` to
+display the content of the slot on that place:
+
+.. code-block:: html+php
+
+    <!-- views/layout.php -->
+    <!doctype html>
+    <html>
+        <head>
+            <title><?php $view['slots']->output('title', 'Default title') ?></title>
+        </head>
+        <body>
+            <?php $view['slots']->output('_content') ?>
+        </body>
+    </html>
+
+The first argument of the method is the name of the slot. The method has an
+optional second argument, which is the default value to use if the slot is not
+available.
+
+The ``_content`` slot is a special slot set by the ``PhpEngine``. It contains
+the content of the subtemplate.
+
+.. caution::
+
+    If you're using the standalone component, make sure you registered the
+    :class:`Symfony\\Component\\Templating\\Helper\\SlotsHelper`::
+
+        use Symfony\Component\Templating\Helper\SlotsHelper;
+
+        // ...
+        $templateEngine->set(new SlotsHelper());
+
+Extending Templates
+~~~~~~~~~~~~~~~~~~~
+
+The :method:`Symfony\\Component\\Templating\\PhpEngine::extend` method is called in the
+sub-template to set its parent template. Then
+:method:`$view['slots']->set()
+<Symfony\\Component\\Translation\\Helper\\SlotsHelper::set>` can be used to
+set the content of a slot. All content which is not explicitly set in a slot
+is in the ``_content`` slot.
+
+.. code-block:: html+php
+
+    <!-- views/page.php -->
+    <?php $view->extend('layout.php') ?>
+
+    <?php $view['slots']->set('title', $page->title) ?>
+
+    <h1>
+        <?php echo $page->title ?>
+    </h1>
+    <p>
+        <?php echo $page->body ?>
+    </p>
+
+.. note::
+
+    Multiple levels of inheritance is possible: a layout can extend an other
+    layout.
+
+For large slots, there is also an extended syntax:
+
+.. code-block:: html+php
+
+    <?php $view['slots']->start('title') ?>
+        Some large amount of HTML
+    <?php $view['slots']->stop() ?>

components/templating/index.rst

@@ -0,0 +1,8 @@
+Templating
+==========
+
+.. toctree::
+    :maxdepth: 2
+
+    introduction
+    helpers/index