From 7698bd83ebc974df7855e4203d2bda0925840956 Mon Sep 17 00:00:00 2001
From: Ben Bangert <ben@groovie.org>
Date: Fri, 29 Oct 2010 23:35:02 -0700
Subject: First set of Mako docs for narrative.

---
 docs/narr/views.rst | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)

(limited to 'docs/narr/views.rst')

diff --git a/docs/narr/views.rst b/docs/narr/views.rst
index 37fb6562b..84c7e0e25 100644
--- a/docs/narr/views.rst
+++ b/docs/narr/views.rst
@@ -563,6 +563,57 @@ Views which use a Chameleon renderer can vary response attributes by
 attaching properties to the request.  See
 :ref:`response_request_attrs`.
 
+.. index::
+   pair: renderer; mako
+
+.. _mako_template_renderers:
+
+``*.mak`` or ``*.mako``: Mako Template Renderer
++++++++++++++++++++++++++++++++++++++++++++++++
+
+The ``Mako`` template renderer is a renderer which renders a Mako template.
+When used, the view must return a Response object or a Python *dictionary*.
+The dictionary items will then be used in the global template space. If the
+view callable returns anything but a Response object or a dictionary, an error
+will be raised.
+
+When using the ``renderer`` attribute to specify a Mako template, the template
+can be specified in two ways. First, a relative path can be used to name a
+Mako template relative to the configured Mako template directories. Second, a
+:term:`resource specification` can be used to locate a template to render.
+These two styles of naming a template to render also carry through to Mako
+templates, so that Mako template's can inherit using a :term:`resource
+specification` if desired.
+
+Here's an example view configuration which uses a relative path:
+
+.. code-block:: xml
+   :linenos:
+
+   <view
+       context=".models.Hello"
+       view=".views.hello_world"
+       name="hello"
+       renderer="foo.mak"
+       />
+
+It's important to note that in Mako's case, the 'relative' path name is not
+relative to the package, but is relative the the directory configured for
+Mako.
+
+Here's an example view configuration which uses a :term:`resource
+specification`:
+
+.. code-block:: xml
+   :linenos:
+
+   <view
+       context=".models.Hello"
+       view=".views.hello_world"
+       name="hello"
+       renderer="some.package:templates/foo.mak"
+       />
+
 .. index::
    single: response headers (from a renderer)
    single: renderer response headers
-- 
cgit v1.2.3