From 0eda298627f2fa1c1668522adb51bbe31356fa7b Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sun, 3 Feb 2013 07:24:02 -0600 Subject: [PATCH 1/2] [#1786] Adding documentation for Twig namespaced paths support --- book/templating.rst | 5 ++ cookbook/map.rst.inc | 1 + cookbook/templating/index.rst | 1 + cookbook/templating/namespaced_paths.rst | 86 ++++++++++++++++++++++++ 4 files changed, 93 insertions(+) create mode 100644 cookbook/templating/namespaced_paths.rst diff --git a/book/templating.rst b/book/templating.rst index 1213a82b072..5edf94b592a 100644 --- a/book/templating.rst +++ b/book/templating.rst @@ -376,6 +376,11 @@ When working with template inheritance, here are some tips to keep in mind: Template Naming and Locations ----------------------------- +.. versionadded:: 2.2 + Namespaced path support was added in 2.2, allowing for template names + like ``@AcmeDemoBundle/layout.html.twig``. See :doc:`/cookbook/templating/namespaced_paths` + for more details. + By default, templates can live in two different locations: * ``app/Resources/views/``: The applications ``views`` directory can contain diff --git a/cookbook/map.rst.inc b/cookbook/map.rst.inc index b6013df58be..9b0d8fd0779 100644 --- a/cookbook/map.rst.inc +++ b/cookbook/map.rst.inc @@ -134,6 +134,7 @@ * :doc:`/cookbook/templating/index` * :doc:`/cookbook/templating/global_variables` + * :doc:`/cookbook/templating/namespaced_paths` * :doc:`/cookbook/templating/PHP` * :doc:`/cookbook/templating/twig_extension` * :doc:`/cookbook/templating/render_without_controller` diff --git a/cookbook/templating/index.rst b/cookbook/templating/index.rst index 21ae6cda73c..46d6fe37012 100644 --- a/cookbook/templating/index.rst +++ b/cookbook/templating/index.rst @@ -5,6 +5,7 @@ Templating :maxdepth: 2 global_variables + namespaced_paths PHP twig_extension render_without_controller diff --git a/cookbook/templating/namespaced_paths.rst b/cookbook/templating/namespaced_paths.rst new file mode 100644 index 00000000000..bced0629f94 --- /dev/null +++ b/cookbook/templating/namespaced_paths.rst @@ -0,0 +1,86 @@ +.. index:: + single: Templating; Namespaced Twig Paths + +How to use and Register namespaced Twig Paths +============================================= + +.. versionadded:: 2.2 + Namespaced path support was added in 2.2. + +Usually, when you refer to a template, you'll use the ``MyBundle:Subdir:filename.html.twig`` +format (see :ref:`template-naming-locations`). + +Twig also natively offers a feature called "namespaced paths", and support +is built-in automatically for all of your bundles. + + +Take the following paths as an example: + +.. code-block:: jinja + + {% extends "AcmeDemoBundle::layout.html.twig" %} + {% include "AcmeDemoBundle:Foo:bar.html.twig" %} + +With namespaced paths, the following works as well: + +.. code-block:: jinja + + {% extends "@AcmeDemo/layout.html.twig" %} + {% include "@AcmeDemo/Foo/bar.html.twig" %} + +Both paths are valid and functional by default in Symfony2. + +.. tip:: + + As an added bonus, the namespaced syntax is faster. + +Registering your own namespaces +------------------------------- + +You can also register your own custom namespaces. Suppose that you're using +some third-party library that includes Twig templates that live in +``vendor/acme/foo-project/templates``. First, register a namespace for this +directory: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + twig: + # ... + paths: + "%kernel.root_dir%/../vendor/acme/foo-bar/templates": foo_bar + + .. code-block:: xml + + + + + + + + %kernel.root_dir%/../vendor/acme/foo-bar/templates + + + + + .. code-block:: php + + // app/config/config.php + $container->loadFromExtension('twig', array( + 'paths' => array( + '%kernel.root_dir%/../vendor/acme/foo-bar/templates' => 'foo_bar' + ); + )); + +The registered namespace is called ``foo_bar``, which refers to the +``vendor/acme/foo-project/templates`` directory. Assuming there's a file +called ``sidebar.twig`` in that directory, you can use it easily: + +.. code-block:: jinja + + {% include '@foo_bar/side.bar.twig` %} \ No newline at end of file From a7ce478ea3b1aacb047f04885e0f3f6fff421d06 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Fri, 8 Feb 2013 08:30:05 -1000 Subject: [PATCH 2/2] [#1786] Tweaks per @WouterJ on #2211 --- cookbook/templating/namespaced_paths.rst | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/cookbook/templating/namespaced_paths.rst b/cookbook/templating/namespaced_paths.rst index bced0629f94..8e33b38ef66 100644 --- a/cookbook/templating/namespaced_paths.rst +++ b/cookbook/templating/namespaced_paths.rst @@ -13,7 +13,6 @@ format (see :ref:`template-naming-locations`). Twig also natively offers a feature called "namespaced paths", and support is built-in automatically for all of your bundles. - Take the following paths as an example: .. code-block:: jinja @@ -55,25 +54,23 @@ directory: .. code-block:: xml - + > %kernel.root_dir%/../vendor/acme/foo-bar/templates - .. code-block:: php // app/config/config.php $container->loadFromExtension('twig', array( 'paths' => array( - '%kernel.root_dir%/../vendor/acme/foo-bar/templates' => 'foo_bar' + '%kernel.root_dir%/../vendor/acme/foo-bar/templates' => 'foo_bar', ); ));