From 201d985a6e560671afa381f1e1cc2733383f4f83 Mon Sep 17 00:00:00 2001
From: Chris McDonough <chrism@agendaless.com>
Date: Sun, 31 May 2009 15:57:07 +0000
Subject: - Add description to narrative templating chapter about how to use  
 Chameleon text templates.

---
 CHANGES.txt             |  9 +++++++++
 docs/narr/templates.rst | 42 +++++++++++++++++++++++++++++++-----------
 2 files changed, 40 insertions(+), 11 deletions(-)

diff --git a/CHANGES.txt b/CHANGES.txt
index 255ffd46c..78c5938f2 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -1,3 +1,12 @@
+Next Release
+============
+
+Documentation
+-------------
+
+- Add description to narrative templating chapter about how to use
+  Chameleon text templates.
+
 0.9a8 (2009-05-31)
 ==================
 
diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst
index 97d29d689..245c1919d 100644
--- a/docs/narr/templates.rst
+++ b/docs/narr/templates.rst
@@ -7,8 +7,8 @@ information.  :mod:`repoze.bfg` offers a number of ways to perform
 templating tasks "out of the box", and provides alternative templating
 language support via add-on "bindings" packages.
 
-Templating With :term:`Chameleon` (:term:`chameleon.zpt`) Page Templates
-------------------------------------------------------------------------
+Templating With :term:`Chameleon` ZPT Page Templates
+----------------------------------------------------
 
 Like :term:`Zope`, :mod:`repoze.bfg` uses Zope Page Templates
 (:term:`ZPT`) as its default and best-supported templating
@@ -180,6 +180,35 @@ And ``templates/mytemplate.pt`` might look like so:
       </span>
     </html>
 
+Templating with :term:`Chameleon` Text Templates
+------------------------------------------------
+
+:mod:`repoze.bfg` also allows for the use of templates which are
+composed entirely of non-XML text via :term:`Chameleon`.  To do so,
+you can create templates that are entirely composed of text except for
+``${name}`` -style substitution points.
+
+Here's an example usage of a Chameleon text template.  Create a file
+on disk named ``text.txt`` in your project's ``templates`` directory
+with the following contents::
+
+   Hello, ${name}!
+
+Then in your project's ``views.py`` module, you can create a view
+which renders this template:
+
+.. code-block:: python
+   :linenos:
+
+   from repoze.bfg.chameleon_text import render_template_to_response
+
+   def text_view(context, request):
+       return render_template_to_response('templates/text.txt', name='World')
+
+The Chameleon text rendering API is a wholesale mirror of the
+Chameleon text ZPT rendering API, it's just imported from another
+place; see :ref:`template_module` for the API description.
+
 Side Effects of Rendering a Chameleon Template
 ----------------------------------------------
 
@@ -235,15 +264,6 @@ application's configuration section, e.g.::
   use = egg:MyProject#app
   reload_templates = true
 
-Using Text Templates
---------------------
-
-:mod:`repoze.bfg` also allows for the use of templates which are
-composed entirely of non-XML text via :term:`Chameleon`.  To do so,
-you can create templates that are entirely composed of text except for
-``${name}`` -style substitution points.  The rendering API is a mirror
-of the ZPT rendering facility, it's just imported from another place;
-see :ref:`template_module` for more information.
 
 Templating with other Templating Languages
 ------------------------------------------
-- 
cgit v1.2.3