From 0e21c22166f5160a2a64fad714d69d81897ef7d3 Mon Sep 17 00:00:00 2001
From: Chris McDonough <chrism@agendaless.com>
Date: Sun, 17 Aug 2008 17:32:54 +0000
Subject:   - Add ``<bfg:settings>`` directive.  This directive currently
 allows     only one attribute: ``reload_templates``.  If e.g.::

         <bfg:settings reload_templates="true"/>

    is in your application's ZCML, you will not need to restart the
    appserver in order for ``z3c.pt`` or XSLT template changes to be
    detected and displayed.
---
 docs/narr/myproject/myproject/configure.zcml |  6 +++++-
 docs/narr/project.rst                        | 20 +++++++++++++++++---
 2 files changed, 22 insertions(+), 4 deletions(-)

(limited to 'docs/narr')

diff --git a/docs/narr/myproject/myproject/configure.zcml b/docs/narr/myproject/myproject/configure.zcml
index 174b27354..6cd692784 100644
--- a/docs/narr/myproject/myproject/configure.zcml
+++ b/docs/narr/myproject/myproject/configure.zcml
@@ -2,9 +2,13 @@
 	   xmlns:bfg="http://namespaces.repoze.org/bfg"
 	   i18n_domain="repoze.bfg">
 
-  <!-- this must be included for the view declarations to work -->
+  <!-- this directive must be included for the view declarations to work -->
   <include package="repoze.bfg" />
 
+  <!-- this directive indicates that changes to templates should show up
+       immediately -->
+  <bfg:settings reload_templates="true"/>
+
   <bfg:view
      for=".models.IMyModel"
      view=".views.my_view"
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index f93dd2a88..98f02a476 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -416,7 +416,10 @@ registry`. It looks like so:
 #. Line 6 initializes :mod:`repoze.bfg`-specific configuration
    directives by including it as a package.
 
-#. Lines 8-11 register a single view.  It is ``for`` model objects
+#. Line 10 tells :mod:`repoze.bfg` to detect changes made to
+ ``z3c.pt`` and XSLT templates immediately.
+
+#. Lines 12-15 register a single view.  It is ``for`` model objects
    that support the IMyModel interface.  The ``view`` attribute points
    at a Python function that does all the work for this view.  Note
    that the values of both the ``for`` attribute and the ``view``
@@ -451,7 +454,16 @@ in the model, and the HTML given back to the browser.
    ``Request`` class representing the browser's request to our server.
 
 #. The view renders a :term:`template` and returns the result as the
-   :term:`response`.
+   :term:`response`.  Note that because our ``configure.zcml`` has a
+   ``bfg:settings`` directive indicating that templates should be
+   reloaded when they change, you won't need to restart the
+   application server to see changes you make to templates.  During
+   development, this is handy.  If this directive had been ``false``
+   (or if the directive did not exist), you would need to restart the
+   application server for each template change.  For production
+   applications, you should set your ``bfg:settings``
+   ``reload_templates`` to ``false`` to increase the speed at which
+   templates may be rendered.
 
 .. note::
 
@@ -460,7 +472,9 @@ in the model, and the HTML given back to the browser.
   the ``render_template`` function, also present in
   :ref:`template_module`.  You may then create your own :term:`WebOb`
   Response object, using the result of ``render_template`` as the
-  response's body.
+  response's body.  There is also a ``get_template`` API in the same
+  module, which you can use to retrieve the template object without
+  rendering it at all, for additional control.
 
 ``models.py``
 ~~~~~~~~~~~~~
-- 
cgit v1.2.3