- Instead of invariably using ``webob.Request`` as the "request

  factory" (e.g. in the ``Router`` class) and ``webob.Response`` and
  the "response factory" (e.g. in ``render_template_to_response``),
  allow both to be overridden via a ZCML utility hook.  See the "Using
  ZCML Hooks" chapter of the documentation for more information.

2 files changed, 49 insertions, 0 deletions

diff --git a/docs/index.rst b/docs/index.rst
index 13edb8a48..4df01341e 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -36,6 +36,7 @@ Narrative documentation in chapter form explaining how to use
    narr/events
    narr/environment
    narr/unittesting
+   narr/hooks
    glossary
 
 API documentation
diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
new file mode 100644
index 000000000..009943e9e
--- /dev/null
+++ b/docs/narr/hooks.rst
@@ -0,0 +1,48 @@
+.. _hooks_chapter:
+
+Using ZCML Hooks
+================
+
+ZCML "hooks" can be used to influence the behavior of the
+:mod:`repoze.bfg` framework in various ways.  This is an advanced
+topic; very few people will want or need to do any of these things.
+
+Changing the request factory
+----------------------------
+
+You may change the class used as the "request factory" from within the
+:mod:`repoze.bfg` ``Router`` class (the ``Router`` class turns the
+WSGI environment into a "request" object which is used ubiquitously
+throughout BFG).  The default "request factory" is the class
+``webob.Request``.  You may change it by placing the following ZCML in
+your ``configure.zcml`` file.
+
+.. code-block:: xml
+   :linenos:
+
+   <utility provides="repoze.bfg.interfaces.IRequestFactory"
+            component=".my.request.factory"/>
+
+Replace ``my.request.factory`` with the Python dotted name to the
+request factory you want to use.
+
+Changing the response factory
+-----------------------------
+
+You may change the class used as the "response factory" from within
+the :mod:`repoze.bfg` ``chameleon_zpt``, ``chameleon_genshi``,
+``chameleon_text`` (the ``render_template_to_response`` function used
+within each) and other various places where a Response object is
+constructed by :mod:`repoze.bfg`.  The default "response factory" is
+the class ``webob.Response``.  You may change it by placing the
+following ZCML in your ``configure.zcml`` file.
+
+.. code-block:: xml
+   :linenos:
+
+   <utility provides="repoze.bfg.interfaces.IResponseFactory"
+            component=".my.response.factory"/>
+
+Replace ``my.response.factory`` with the Python dotted name to the
+response factory you want to use.
+