- Document the ``request.override_renderer`` attribute within the narrative

  "Renderers" chapter in a section named "Overriding A Renderer at Runtime".

4 files changed, 56 insertions, 14 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index 48d01c28b..b17dfe88b 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -28,6 +28,9 @@ Documentation
   ``pyramid.testing.tearDown`` instead of Configurator creation and
   ``Configurator.begin()`` and ``Configurator.end()``.
 
+- Document the ``request.override_renderer`` attribute within the narrative
+  "Renderers" chapter in a section named "Overriding A Renderer at Runtime".
+
 1.0a9 (2011-01-08)
 ==================
 
diff --git a/TODO.txt b/TODO.txt
index c8e2a327f..ecc37708a 100644
--- a/TODO.txt
+++ b/TODO.txt
@@ -20,8 +20,6 @@ Must-Have (before 1.0)
 
 - Add docs for ``__action_decorator__`` attr of handler.
 
-- Document the ``request.override_renderer`` attribute.
-
 - Figure out how to slim the herd of paster templates.
 
 - Explain i18n in Mako and Jinja2.
diff --git a/docs/narr/declarative.rst b/docs/narr/declarative.rst
index f36e55b29..5c731ab06 100644
--- a/docs/narr/declarative.rst
+++ b/docs/narr/declarative.rst
@@ -1068,15 +1068,15 @@ See :ref:`aclauthorizationpolicy_directive` for detailed information.
 
 .. _zcml_adding_and_overriding_renderers:
 
-Adding and Overriding Renderers via ZCML
-----------------------------------------
+Adding and Changing Renderers via ZCML
+--------------------------------------
 
 New templating systems and serializers can be associated with :app:`Pyramid`
 renderer names.  To this end, configuration declarations can be made which
-override an existing :term:`renderer factory` and which add a new renderer
+change an existing :term:`renderer factory` and which add a new renderer
 factory.
 
-Adding or overriding a renderer via ZCML is accomplished via the
+Adding or changing an existing renderer via ZCML is accomplished via the
 :ref:`renderer_directive` ZCML directive.
 
 For example, to add a renderer which renders views which have a
@@ -1163,7 +1163,7 @@ with ``.jinja2`` as its ``renderer`` value.  The ``name`` passed to the
 See also :ref:`renderer_directive` and
 :meth:`pyramid.config.Configurator.add_renderer`.
 
-Overriding an Existing Renderer
+Changing an Existing Renderer
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 You can associate more than one filename extension with the same
@@ -1184,7 +1184,7 @@ After you do this, :app:`Pyramid` will treat templates ending in
 both the ``.pt`` and ``.zpt`` filename extensions as Chameleon ZPT
 templates.
 
-To override the default mapping in which files with a ``.pt``
+To change the default mapping in which files with a ``.pt``
 extension are rendered via a Chameleon ZPT page template renderer, use
 a variation on the following in your application's ZCML:
 
@@ -1200,7 +1200,7 @@ After you do this, the :term:`renderer factory` in
 ``my.package.pt_renderer`` will be used to render templates which end
 in ``.pt``, replacing the default Chameleon ZPT renderer.
 
-To override the default mapping in which files with a ``.txt``
+To ochange the default mapping in which files with a ``.txt``
 extension are rendered via a Chameleon text template renderer, use a
 variation on the following in your application's ZCML:
 
diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst
index d888e3376..56d0a5199 100644
--- a/docs/narr/renderers.rst
+++ b/docs/narr/renderers.rst
@@ -389,12 +389,12 @@ documentation in :ref:`request_module`.
 
 .. _adding_and_overriding_renderers:
 
-Adding and Overriding Renderers
--------------------------------
+Adding and Changing Renderers
+-----------------------------
 
 New templating systems and serializers can be associated with :app:`Pyramid`
 renderer names.  To this end, configuration declarations can be made which
-override an existing :term:`renderer factory`, and which add a new renderer
+change an existing :term:`renderer factory`, and which add a new renderer
 factory.
 
 Renderers can be registered imperatively using the
@@ -546,7 +546,7 @@ set as ``renderer=`` in the view configuration.
 See also :ref:`renderer_directive` and
 :meth:`pyramid.config.Configurator.add_renderer`.
 
-Overriding an Existing Renderer
+Changing an Existing Renderer
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 You can associate more than one filename extension with the same existing
@@ -563,7 +563,7 @@ extension for the same kinds of templates.  For example, to associate the
 After you do this, :app:`Pyramid` will treat templates ending in both the
 ``.pt`` and ``.zpt`` filename extensions as Chameleon ZPT templates.
 
-To override the default mapping in which files with a ``.pt`` extension are
+To change the default mapping in which files with a ``.pt`` extension are
 rendered via a Chameleon ZPT page template renderer, use a variation on the
 following in your application's startup code:
 
@@ -585,3 +585,44 @@ the ``name`` attribute to the renderer tag:
 
    config.add_renderer(None, 'mypackage.json_renderer_factory')
 
+Overriding A Renderer At Runtime
+--------------------------------
+
+.. warning:: This is an advanced feature, not typically used by "civilians".
+
+In some circumstances, it is necessary to instruct the system to ignore the
+static renderer declaration provided by the developer in view configuration,
+replacing the renderer with another *after a request starts*.  For example,
+an "omnipresent" XML-RPC implementation that detects that the request is from
+an XML-RPC client might override a view configuration statement made by the
+user instructing the view to use a template renderer with one that uses an
+XML-RPC renderer.  This renderer would produce an XML-RPC representation of
+the data returned by an arbitrary view callable.
+
+To use this feature, create a :class:`pyramid.events.NewRequest`
+:term:`subscriber` which sniffs at the request data and which conditionally
+sets an ``override_renderer`` attribute on the request itself, which is the
+*name* of a registered renderer.  For example:
+
+.. code-block:: python
+   :linenos:
+
+   from pyramid.event import subscriber
+   from pyramid.event import NewRequest
+
+   @subscriber(NewRequest)
+   def set_xmlrpc_params(event):
+       request = event.request
+       if (request.content_type == 'text/xml'
+           and request.method == 'POST'
+           and not 'soapaction' in request.headers
+           and not 'x-pyramid-avoid-xmlrpc' in request.headers):
+           params, method = parse_xmlrpc_request(request)
+           request.xmlrpc_params, request.xmlrpc_method = params, method
+           request.is_xmlrpc = True
+           request.override_renderer = 'xmlrpc'
+           return True
+
+The result of such a subscriber will be to replace any existing static
+renderer configured by the developer with a (notional, nonexistent) XML-RPC
+renderer if the request appears to come from an XML-RPC client.