add docs about chameleon zpt macro feature

Chris McDonough

2012-08-29 eecaa867d72d06fec45dd151fcd2e93d02927cef

add docs about chameleon zpt macro feature

 docs/narr/templates.rst

@@ -534,6 +534,30 @@
      </span>
    </html>


Using A Chameleon Macro Name Within a Chameleon ZPT Template
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Sommetime you'd like to render a macro inside of a Chameleon ZPT template
instead of the full Chameleon ZPT template. To render the content of a
``define-macro`` field inside a Chameleon ZPT template, given a Chameleon
template file named ``foo.pt`` and a macro named ``bar`` defined within it
(e.g. ``<div metal:define-macro="bar">...</div>``, you can configure the
template as a :term:`renderer` like so:

.. code-block:: python
   :linenos:

   from pyramid.view import view_config

   @view_config(renderer='foo#bar.pt')
   def my_view(request):
       return {'project':'my project'}

The above will render the ``bar`` macro from within the ``foo.pt`` template
instead of the entire template.


.. index::
   single: Chameleon text templates

@@ -714,12 +738,13 @@
:term:`renderer globals`.  See the `the Mako documentation
<http://www.makotemplates.org/>`_ to use more advanced features.

Using def inside Mako Templates
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Using A Mako def name Within a Renderer Name
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To use a def inside a Mako template, given a :term:`Mako` template file named 
``foo.mak`` and a def named ``bar``, you can configure the template as a 
:term:`renderer` like so:
Sommetime you'd like to render a ``def`` inside of a Mako template instead of
the full Mako template. To render a def inside a Mako template, given a
:term:`Mako` template file named ``foo.mak`` and a def named ``bar``, you can
configure the template as a :term:`renderer` like so:

.. code-block:: python
   :linenos:
@@ -730,6 +755,9 @@
   def my_view(request):
       return {'project':'my project'}

The above will render the ``bar`` def from within the ``foo.mak`` template
instead of the entire template.

.. index::
   single: automatic reloading of templates
   single: template automatic reload