From 3a9f14068a9dca42b7c2734f4a2d7124e48623b8 Mon Sep 17 00:00:00 2001 From: WouterJ Date: Tue, 18 Feb 2014 22:14:55 +0100 Subject: [PATCH 1/4] Added globals section --- components/templating/introduction.rst | 27 ++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/components/templating/introduction.rst b/components/templating/introduction.rst index 130358677a9..b4cc6c96df5 100644 --- a/components/templating/introduction.rst +++ b/components/templating/introduction.rst @@ -73,6 +73,33 @@ to render the template originally) inside the template to render another templat render('hello.php', array('firstname' => $name)) ?> +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 + +

The google tracking code is:

+ +.. 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 --------------- From e2434855bdc5fdf694fbef05b9eb9394535e0d6a Mon Sep 17 00:00:00 2001 From: WouterJ Date: Tue, 18 Feb 2014 22:21:40 +0100 Subject: [PATCH 2/4] Added a note on caching --- components/templating/introduction.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/components/templating/introduction.rst b/components/templating/introduction.rst index b4cc6c96df5..d2f10db9695 100644 --- a/components/templating/introduction.rst +++ b/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 ---------------------- From 9f34675db2bc00a2e6b448f68dca05be28760b4e Mon Sep 17 00:00:00 2001 From: WouterJ Date: Tue, 18 Feb 2014 22:32:20 +0100 Subject: [PATCH 3/4] Documented custom engines and DelegatingEngine --- components/templating/introduction.rst | 37 ++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/components/templating/introduction.rst b/components/templating/introduction.rst index d2f10db9695..3a33b033e2b 100644 --- a/components/templating/introduction.rst +++ b/components/templating/introduction.rst @@ -161,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` +interface. This interface requires 3 method: + +* :method:`render($name, array $parameters = array()) ` + - Renders a template +* :method:`exists($name) ` + - Checks if the template exists +* :method:`supports($name) ` + - 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() ` +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 From b215395d920bca4325f363d84398fadeb3579355 Mon Sep 17 00:00:00 2001 From: WouterJ Date: Sat, 8 Mar 2014 19:24:08 +0100 Subject: [PATCH 4/4] Applied comment from @weaverryan --- components/templating/introduction.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/components/templating/introduction.rst b/components/templating/introduction.rst index 3a33b033e2b..12c5e29f790 100644 --- a/components/templating/introduction.rst +++ b/components/templating/introduction.rst @@ -166,8 +166,8 @@ 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` -interface. This interface requires 3 method: +implements the :class:`Symfony\\Component\\Templating\\EngineInterface`. This +requires 3 method: * :method:`render($name, array $parameters = array()) ` - Renders a template