Permalink
Browse files

feature #3589 Finishing the Templating component docs (WouterJ)

This PR was merged into the 2.3 branch.

Discussion
----------

Finishing the Templating component docs

| Q   | A
| --- | ---
| Doc fix? | no
| New docs? | yes
| Applies to | all
| Fixed tickets | #955

Fixed the remeaning tasks of #955 (comment)

Commits
-------

b215395 Applied comment from @weaverryan
9f34675 Documented custom engines and DelegatingEngine
e243485 Added a note on caching
3a9f140 Added globals section
  • Loading branch information...
weaverryan committed Mar 9, 2014
2 parents d881181 + b215395 commit 56bc2660041162c828cdad6c64a722a602c1f126
Showing with 70 additions and 0 deletions.
  1. +70 −0 components/templating/introduction.rst
@@ -52,6 +52,12 @@ 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!``.
.. note::
Templates will be cached in the memory of the engine. This means that if
you render the same template multiple times in the same request, the
template will only be loaded once from the file system.
The ``$view`` variable
----------------------
@@ -73,6 +79,33 @@ to render the template originally) inside the template to render another templat
<?php echo $view->render('hello.php', array('firstname' => $name)) ?>
<?php endforeach ?>
Global Variables
----------------
Sometimes, you need to set a variable which is available in all templates
rendered by an engine (like the ``$app`` variable when using the Symfony2
framework). These variables can be set by using the
:method:`Symfony\\Component\\Templating\\PhpEngine::addGlobal` method and they
can be accessed in the template as normal variables::
$templating->addGlobal('ga_tracking', 'UA-xxxxx-x');
In a template:
.. code-block:: html+php
<p>The google tracking code is: <?php echo $ga_tracking ?></p>
.. caution::
The global variables cannot be called ``this`` or ``view``, since they are
already used by the PHP engine.
.. note::
The global variables can be overriden by a local variable in the template
with the same name.
Output Escaping
---------------
@@ -128,4 +161,41 @@ 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.
Creating a Custom Engine
------------------------
Besides providing a PHP templating engine, you can also create your own engine
using the Templating component. To do that, create a new class which
implements the :class:`Symfony\\Component\\Templating\\EngineInterface`. This
requires 3 method:
* :method:`render($name, array $parameters = array()) <Symfony\\Component\\Templating\\EngineInterface::render>`
- Renders a template
* :method:`exists($name) <Symfony\\Component\\Templating\\EngineInterface::exists>`
- Checks if the template exists
* :method:`supports($name) <Symfony\\Component\\Templating\\EngineInterface::supports>`
- Checks if the given template can be handled by this engine.
Using Multiple Engines
----------------------
It is possible to use multiple engines at the same time using the
:class:`Symfony\\Component\\Templating\\DelegatingEngine` class. This class
takes a list of engines and acts just like a normal templating engine. The
only difference is that it delegates the calls to one of the other engines. To
choose which one to use for the template, the
:method:`EngineInterface::supports() <Symfony\\Component\\Templating\\EngineInterface::supports>`
method is used.
.. code-block:: php
use Acme\Templating\CustomEngine;
use Symfony\Component\Templating\PhpEngine;
use Symfony\Component\Templating\DelegatingEngine;
$templating = new DelegatingEngine(array(
new PhpEngine(...),
new CustomEngine(...)
));
.. _Packagist: https://packagist.org/packages/symfony/templating

0 comments on commit 56bc266

Please sign in to comment.