From 7a46d3068c0f53e3f4f4701c6012564fab069c1f Mon Sep 17 00:00:00 2001 From: WouterJ Date: Sun, 16 Jun 2013 17:39:08 +0200 Subject: [PATCH] Rewrote Templating Docs --- components/index.rst | 2 +- components/map.rst.inc | 4 +- components/templating.rst | 113 --------------- .../templating/helpers/assetshelper.rst | 102 ++++++++++++++ components/templating/helpers/index.rst | 16 +++ components/templating/helpers/map.rst.inc | 2 + components/templating/helpers/slotshelper.rst | 84 ++++++++++++ components/templating/index.rst | 8 ++ components/templating/introduction.rst | 129 ++++++++++++++++++ cookbook/templating/PHP.rst | 2 +- redirection_map | 1 + 11 files changed, 346 insertions(+), 117 deletions(-) delete mode 100644 components/templating.rst create mode 100644 components/templating/helpers/assetshelper.rst create mode 100644 components/templating/helpers/index.rst create mode 100644 components/templating/helpers/map.rst.inc create mode 100644 components/templating/helpers/slotshelper.rst create mode 100644 components/templating/index.rst create mode 100644 components/templating/introduction.rst diff --git a/components/index.rst b/components/index.rst index 090152afa61..865b2b274e6 100644 --- a/components/index.rst +++ b/components/index.rst @@ -24,7 +24,7 @@ The Components security/index serializer stopwatch - templating + templating/index yaml/index .. include:: /components/map.rst.inc diff --git a/components/map.rst.inc b/components/map.rst.inc index c14df50277c..2e92fbab740 100644 --- a/components/map.rst.inc +++ b/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` diff --git a/components/templating.rst b/components/templating.rst deleted file mode 100644 index de53eec0cc4..00000000000 --- a/components/templating.rst +++ /dev/null @@ -1,113 +0,0 @@ -.. index:: - single: Templating - single: Components; Templating - -The Templating Component -======================== - - Templating provides all the tools needed to build any kind of template - system. - - It provides an infrastructure to load template files and optionally monitor - them for changes. It also provides a concrete template engine implementation - using PHP with additional tools for escaping and separating templates into - blocks and layouts. - -Installation ------------- - -You can install the component in 2 different ways: - -* Use the official Git repository (https://github.com/symfony/Templating); -* :doc:`Install it via Composer ` (``symfony/templating`` on `Packagist`_). - -Usage ------ - -The :class:`Symfony\\Component\\Templating\\PhpEngine` class is the entry point -of the component. It needs a template name parser -(:class:`Symfony\\Component\\Templating\\TemplateNameParserInterface`) to -convert a template name to a template reference and template loader -(:class:`Symfony\\Component\\Templating\\Loader\\LoaderInterface`) to find the -template associated to a reference:: - - use Symfony\Component\Templating\PhpEngine; - use Symfony\Component\Templating\TemplateNameParser; - use Symfony\Component\Templating\Loader\FilesystemLoader; - - $loader = new FilesystemLoader(__DIR__ . '/views/%name%'); - - $view = new PhpEngine(new TemplateNameParser(), $loader); - - echo $view->render('hello.php', array('firstname' => 'Fabien')); - -The :method:`Symfony\\Component\\Templating\\PhpEngine::render` method executes -the file `views/hello.php` and returns the output text. - -.. code-block:: html+php - - - Hello, ! - -Template Inheritance with Slots -------------------------------- - -The template inheritance is designed to share layouts with many templates. - -.. code-block:: html+php - - - - - <?php $view['slots']->output('title', 'Default title') ?> - - - output('_content') ?> - - - -The :method:`Symfony\\Component\\Templating\\PhpEngine::extend` method is called in the -sub-template to set its parent template. - -.. code-block:: html+php - - - extend('layout.php') ?> - - set('title', $page->title) ?> - -

- title ?> -

-

- body ?> -

- -To use template inheritance, the :class:`Symfony\\Component\\Templating\\Helper\\SlotsHelper` -helper must be registered:: - - use Symfony\Component\Templating\Helper\SlotsHelper; - - $view->set(new SlotsHelper()); - - // Retrieve page object - $page = ...; - - echo $view->render('page.php', array('page' => $page)); - -.. note:: - - Multiple levels of inheritance is possible: a layout can extend an other - layout. - -Output Escaping ---------------- - -This documentation is still being written. - -The Asset Helper ----------------- - -This documentation is still being written. - -.. _Packagist: https://packagist.org/packages/symfony/templating diff --git a/components/templating/helpers/assetshelper.rst b/components/templating/helpers/assetshelper.rst new file mode 100644 index 00000000000..9a35fb90324 --- /dev/null +++ b/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 + + + + + +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 + + + + +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 + + + + +Custom Packages +--------------- + +You can create your own package by extending +:class:`Symfony\\Component\\Templating\\Package\\Package`. diff --git a/components/templating/helpers/index.rst b/components/templating/helpers/index.rst new file mode 100644 index 00000000000..572c5aebe4d --- /dev/null +++ b/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 diff --git a/components/templating/helpers/map.rst.inc b/components/templating/helpers/map.rst.inc new file mode 100644 index 00000000000..7af793aaa1c --- /dev/null +++ b/components/templating/helpers/map.rst.inc @@ -0,0 +1,2 @@ +* :doc:`/components/templating/helpers/slotshelper` +* :doc:`/components/templating/helpers/assetshelper` diff --git a/components/templating/helpers/slotshelper.rst b/components/templating/helpers/slotshelper.rst new file mode 100644 index 00000000000..e79cc88c09e --- /dev/null +++ b/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 + + + + + + <?php $view['slots']->output('title', 'Default title') ?> + + + output('_content') ?> + + + +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() +` 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 + + + extend('layout.php') ?> + + set('title', $page->title) ?> + +

+ title ?> +

+

+ body ?> +

+ +.. 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 + + start('title') ?> + Some large amount of HTML + stop() ?> diff --git a/components/templating/index.rst b/components/templating/index.rst new file mode 100644 index 00000000000..6db2575e8f6 --- /dev/null +++ b/components/templating/index.rst @@ -0,0 +1,8 @@ +Templating +========== + +.. toctree:: + :maxdepth: 2 + + introduction + helpers/index diff --git a/components/templating/introduction.rst b/components/templating/introduction.rst new file mode 100644 index 00000000000..d6704abb3ac --- /dev/null +++ b/components/templating/introduction.rst @@ -0,0 +1,129 @@ +.. index:: + single: Templating + single: Components; Templating + +The Templating Component +======================== + + The Templating Component provides all the tools needed to build any kind + of template system. + + It provides an infrastructure to load template files and optionally + monitor them for changes. It also provides a concrete template engine + implementation using PHP with additional tools for escaping and separating + templates into blocks and layouts. + +Installation +------------ + +You can install the component in 2 different ways: + +* Use the official Git repository (https://github.com/symfony/Templating); +* :doc:`Install it via Composer ` (``symfony/templating`` on `Packagist`_). + +Usage +----- + +The :class:`Symfony\\Component\\Templating\\PhpEngine` class is the entry point +of the component. It needs a +:class:`template name parser ` +to convert a template name to a +:class:`template reference ` +and :class:`template loader ` +to find the template associated to a reference:: + + use Symfony\Component\Templating\PhpEngine; + use Symfony\Component\Templating\TemplateNameParser; + use Symfony\Component\Templating\Loader\FilesystemLoader; + + $loader = new FilesystemLoader(__DIR__.'/views/%name%'); + + $templating = new PhpEngine(new TemplateNameParser(), $loader); + + echo $templating->render('hello.php', array('firstname' => 'Fabien')); + +.. code-block:: html+php + + + Hello, ! + +The :method:`Symfony\\Component\\Templating\\PhpEngine::render` method parses +the ``views/hello.php`` file and returns the output text. The second argument +of ``render`` is an array of variables to use in the template. In this +example, the result will be ``Hello, Fabien!``. + +The ``$view`` variable +---------------------- + +In all templates parsed by the ``PhpEngine``, you get access to a mysterious +variable called ``$view``. That variable holds the current ``PhpEngine`` +instance. That means you get access to a bunch of methods that makes your life +easier. + +Including Templates +------------------- + +The best way to share a snippet of template code is to define a template that +can then be included into other templates. As the ``$view`` variable is an +instance of ``PhpEngine``, you can use the ``render`` method (which was used +to render the template) inside the template to render another template:: + + + + render('hello.php', array('firstname' => $name)) ?> + + +Output Escaping +--------------- + +When you display variables to the user, you should escape them using the +:method:`Symfony\\Component\\Templating\\PhpEngine::escape` method:: + + escape($firstname) ?> + +By default, the ``escape()`` method assumes that the variable is outputted +within an HTML context. The second argument lets you change the context. For +instance, to output something in a JavaScript script, use the ``js`` context:: + + escape($var, 'js') ?> + +The components comes with a HTML and JS escaper. You can register your own +escaper using the +:method:`Symfony\\Component\\Templating\\PhpEngine::setEscaper` method:: + + $templating->setEscaper('css', function ($value) { + // ... all CSS escaping + + return $escapedValue; + }); + +Helpers +------- + +The Templating component can be easily extended via helpers. The component has +2 build-in helpers: + +* :doc:`/components/helpers/assetshelper` +* :doc:`/components/helpers/slotshelper` + +Before you can use these helpers, you need to register them using +:method:`Symfony\\Component\\Templating\\PhpEngine::set`:: + + use Symfony\Component\Templating\Helper\AssetsHelper; + // ... + + $templating->set(new AssetsHelper()); + +Custom Helpers +~~~~~~~~~~~~~~ + +You can create your own helpers by creating a class which implements +:class:`Symfony\\Component\\Templating\\Helper\\HelperInterface`. However, +most of the time you'll extend +:class:`Symfony\\Component\\Templating\\Helper\\Helper`. + +The ``Helper`` has one required method: +:method:`Symfony\\Component\\Templating\\Helper\\HelperInterface::getName`. +This is the name that is used to get the helper from the ``$view`` object. + +.. _Packagist: https://packagist.org/packages/symfony/templating diff --git a/cookbook/templating/PHP.rst b/cookbook/templating/PHP.rst index 40f03611fd0..24a1b16d488 100644 --- a/cookbook/templating/PHP.rst +++ b/cookbook/templating/PHP.rst @@ -4,7 +4,7 @@ How to use PHP instead of Twig for Templates ============================================ -Even if Symfony2 defaults to Twig for its template engine, you can still use +Symfony2 defaults to Twig for its template engine, but you can still use plain PHP code if you want. Both templating engines are supported equally in Symfony2. Symfony2 adds some nice features on top of PHP to make writing templates with PHP more powerful. diff --git a/redirection_map b/redirection_map index 054ad65c416..36dd9800c63 100644 --- a/redirection_map +++ b/redirection_map @@ -20,3 +20,4 @@ /components/routing /components/routing/introduction /cookbook/console/generating_urls /cookbook/console/sending_emails /components/yaml /components/yaml/introduction +/components/templating /components/templating/introduction