Cleaning up new entry on global variables

cookbook/index.rst

@@ -64,6 +64,7 @@ Cookbook
 
     cache/varnish
 
+    templating/global_variables
     templating/PHP
 
     tools/autoloader

cookbook/map.rst.inc

@@ -85,6 +85,7 @@
 
 * **Templating**
 
+  * :doc:`/cookbook/templating/global_variables`
   * :doc:`/cookbook/templating/PHP`
 
 * **Tools, Logging and Internals**

cookbook/templating/global_variables.rst

@@ -1,36 +1,48 @@
-Injecting variables into all templates
-======================================
+.. index::
+   single: Templating; Global variables
 
-Sometimes you want a variable to be accessable to all the templates you use, here's how.
+Injecting variables into all templates (i.e. Global Variables)
+==============================================================
 
-If you set a parameter in parameters.ini then you will have to make it accessable by 
-defining it as a global in the twig section of config.yml.
+Sometimes you want a variable to be accessible to all the templates you use.
+This is possible inside your ``app/config/config.yml`` file:
 
-.. code-block: ini
-    [parameters]
-        ga_tracking: UA-xxxxx-x
+.. code-block:: yaml
 
-.. code-block: yaml
+    # app/config/config.yml
     twig:
-        debug:            %kernel.debug%
-        strict_variables: %kernel.debug%
+        # ...
         globals:
-            ga_tracking: %ga_tracking%
+            ga_tracking: UA-xxxxx-x
 
-.. code-block: twig
-    <p>Our google tracking code is: {{ga_tracking}} </p>
+Now, the variable ``ga_tracking`` is available in all Twig templates:
 
-Of course, you can also define the parameter directly in twig:
+.. code-block:: html+jinja
 
+    <p>Our google tracking code is: {{ ga_tracking }} </p>
 
-.. code-block: yaml
-    twig:
-        debug:            %kernel.debug%
-        strict_variables: %kernel.debug%
-        globals:
-            ga_tracking: UA-xxxxx-x
+It's that easy! You can also take advantage of the built-in :ref:`book-service-container-parameters`
+system, which lets you isolate or reuse the value:
 
+.. code-block:: ini
 
+    ; app/config/parameters.ini
+    [parameters]
+        ga_tracking: UA-xxxxx-x
+
+.. code-block:: yaml
+
+    # app/config/config.yml
+    twig:
+        globals:
+            ga_tracking: %ga_tracking%
 
+The same variable is available exactly as before.
 
+More Complex Global Variables
+-----------------------------
 
+If the global variable you want to set is more complicated - say an object -
+then you won't be able to use the above method. Instead, you'll need to create
+a :ref:`Twig Extension<reference-dic-tags-twig-extension>` and return the
+global variable as one of the entries in the ``getGlobals`` method.

reference/dic_tags.rst

@@ -79,6 +79,10 @@ configuration, and tag it with ``twig.extension``:
             ->addTag('twig.extension')
         ;
 
+For information on how to create the actual Twig Extension class, see
+`Twig's documentation`_ on the topic.
+
+
 .. _dic-tags-kernel-event-listener:
 
 Enabling Custom Listeners
@@ -312,3 +316,5 @@ channel used in the Security component:
 
     You cannot use both the ``handler`` and ``channel`` attributes for the
     same tag as handlers are shared between all channels.
+
+..  _`Twig's documentation`: http://twig.sensiolabs.org/doc/extensions.html