From a319249fdb6e0539e65e0b297829ed8c7f799b98 Mon Sep 17 00:00:00 2001
From: Jeff Cook <jeff@deserettechnology.com>
Date: Thu, 7 Jun 2012 14:00:07 -0600
Subject: Update documentation to clarify purpose of
 BeforeRender.rendering_val.

---
 docs/narr/hooks.rst | 15 +++++++++++++++
 pyramid/events.py   | 20 ++++++++++++++++----
 2 files changed, 31 insertions(+), 4 deletions(-)

diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index a2143b3c5..30eec04f0 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -289,6 +289,21 @@ keys added to the renderer globals dictionary by all
 :class:`pyramid.events.BeforeRender` subscribers and renderer globals
 factories must be unique.
 
+The dictionary returned from the view is accessible through the
+:attr:`rendering_val` attribute of a :class:`~pyramid.events.BeforeRender`
+event, like so:
+
+.. code-block:: python
+    :linenos:
+
+    from pyramid.events import subscriber
+    from pyramid.events import BeforeRender
+
+    @subscriber(BeforeRender)
+    def read_return(event):
+        # 'mykey' is returned from the view
+        print(event.rendering_val['mykey'])
+
 See the API documentation for the :class:`~pyramid.events.BeforeRender` event
 interface at :class:`pyramid.interfaces.IBeforeRender`.
 
diff --git a/pyramid/events.py b/pyramid/events.py
index e181ef33f..1941c594c 100644
--- a/pyramid/events.py
+++ b/pyramid/events.py
@@ -200,10 +200,22 @@ class BeforeRender(dict):
     setting an overriding value (which can be done using ``.get`` or
     ``__contains__`` of the event object).
 
-    The event has an additional attribute named ``rendering_val``.  This is
-    the (non-system) value returned by a view or passed to ``render*`` as
-    ``value``.  This feature is new in Pyramid 1.2.
-    
+    The dictionary returned from the view is accessible through the
+    :attr:`rendering_val` attribute of a :class:`~pyramid.events.BeforeRender`
+    event, like so::
+
+      from pyramid.events import subscriber
+      from pyramid.events import BeforeRender
+
+      @subscriber(BeforeRender)
+      def read_return(event):
+          # "mykey" is returned from the view
+          print(event.rendering_val['mykey'])
+
+    In other words, ``rendering_val`` is the (non-system) value returned by a
+    view or passed to ``render*`` as ``value``.  This feature is new in Pyramid
+    1.2.
+
     For a description of the values present in the renderer globals dictionary,
     see :ref:`renderer_system_values`.
 
-- 
cgit v1.2.3