6 files changed, 76 insertions, 14 deletions
diff --git a/docs/api/request.rst b/docs/api/request.rst
index 5dfb2ae9a..404825d1b 100644
--- a/docs/api/request.rst
+++ b/docs/api/request.rst
@@ -180,12 +180,12 @@
       object (exposed to view code as ``request.response``) to influence
       rendered response behavior.
 
-   .. attribute:: json
+   .. attribute:: json_body
 
-      If the request's ``content_type`` is ``application/json``, this
-      attribute will contain the JSON-decoded variant of the request body.
-      If the request's ``content_type`` is not ``application/json``, this
-      attribute will be ``None``.
+       This property will return the JSON-decoded variant of the request
+       body.  If the request body is not well-formed JSON, or there is no
+       body associated with this request, this property will raise an
+       exception.  See also :ref:`request_json_body`.
 
 .. note::
 
diff --git a/docs/designdefense.rst b/docs/designdefense.rst
index ce3c507c5..b285524c6 100644
--- a/docs/designdefense.rst
+++ b/docs/designdefense.rst
@@ -1125,10 +1125,11 @@ Self-described "microframeworks" exist: `Bottle <http://bottle.paws.de>`_ and
 <http://bobo.digicool.com/>`_ doesn't describe itself as a microframework,
 but its intended userbase is much the same.  Many others exist.  We've
 actually even (only as a teaching tool, not as any sort of official project)
-`created one using BFG <http://bfg.repoze.org/videos#groundhog1>`_ (the
-precursor to Pyramid). Microframeworks are small frameworks with one common
-feature: each allows its users to create a fully functional application that
-lives in a single Python file.
+`created one using Pyramid <http://bfg.repoze.org/videos#groundhog1>`_ (the
+videos use BFG, a precursor to Pyramid, but the resulting code is `available
+for Pyramid too <http://github.com/Pylons/groundhog>`_). Microframeworks are
+small frameworks with one common feature: each allows its users to create a
+fully functional application that lives in a single Python file.
 
 Some developers and microframework authors point out that Pyramid's "hello
 world" single-file program is longer (by about five lines) than the
diff --git a/docs/glossary.rst b/docs/glossary.rst
index e45317dae..c8943acae 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -506,6 +506,9 @@ Glossary
      `JavaScript Object Notation <http://www.json.org/>`_ is a data
      serialization format.
 
+   jQuery
+     A popular `Javascript library <http://jquery.org>`_.
+
    renderer
      A serializer that can be referred to via :term:`view
      configuration` which converts a non-:term:`Response` return
diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst
index 97e3ebc55..365ee395b 100644
--- a/docs/narr/sessions.rst
+++ b/docs/narr/sessions.rst
@@ -288,7 +288,7 @@ Preventing Cross-Site Request Forgery Attacks
 `Cross-site request forgery
 <http://en.wikipedia.org/wiki/Cross-site_request_forgery>`_ attacks are a
 phenomenon whereby a user with an identity on your website might click on a
-URL or button on another website which unwittingly redirects the user to your
+URL or button on another website which secretly redirects the user to your
 application to perform some command that requires elevated privileges.
 
 You can avoid most of these attacks by making sure that the correct *CSRF
diff --git a/docs/narr/webob.rst b/docs/narr/webob.rst
index 0ff8e1de7..beb319084 100644
--- a/docs/narr/webob.rst
+++ b/docs/narr/webob.rst
@@ -78,6 +78,10 @@ object:
     ``PUT``.  You can also get ``req.body_file`` for a file-like
     object.
 
+``req.json_body``
+    The JSON-decoded contents of the body of the request. See
+    :ref:`request_json_body`.
+
 ``req.cookies``:
     A simple dictionary of all the cookies.
 
@@ -239,6 +243,56 @@ tuples; all the keys are ordered, and all the values are ordered.
 API documentation for a multidict exists as
 :class:`pyramid.interfaces.IMultiDict`.
 
+.. _request_json_body:
+
+Dealing With A JSON-Encoded Request Body
+++++++++++++++++++++++++++++++++++++++++
+
+.. note:: this feature is new as of Pyramid 1.1.
+
+:attr:`pyramid.request.Request.json_body` is a property that returns a
+:term:`JSON` -decoded representation of the request body.  If the request
+does not have a body, or the body is not a properly JSON-encoded value, an
+exception will be raised when this attribute is accessed.
+
+This attribute is useful when you invoke a Pyramid view callable via
+e.g. jQuery's ``$.ajax`` function, which has the potential to send a request
+with a JSON-encoded body.
+
+Using ``request.json_body`` is equivalent to:
+
+.. code-block:: python
+
+   from json import loads
+   loads(request.body, encoding=request.charset)
+
+Here's how to construct an AJAX request in Javascript using :term:`jQuery`
+that allows you to use the ``request.json_body`` attribute when the request
+is sent to a Pyramid application:
+
+.. code-block:: javascript
+
+    jQuery.ajax({type:'POST', 
+                 url: 'http://localhost:6543/', // the pyramid server
+                 data: JSON.stringify({'a':1}), 
+                 contentType: 'application/json; charset=utf-8'});
+
+When such a request reaches a view in your application, the
+``request.json_body`` attribute will be available in the view callable body.
+
+.. code-block:: javascript
+
+    @view_config(renderer='string')
+    def aview(request):
+        print request.json_body
+        return 'OK'
+
+For the above view, printed to the console will be:
+
+.. code-block:: python
+
+    {u'a': 1}
+
 More Details
 ++++++++++++
 
diff --git a/docs/whatsnew-1.1.rst b/docs/whatsnew-1.1.rst
index fdf3b1c74..a9df38a45 100644
--- a/docs/whatsnew-1.1.rst
+++ b/docs/whatsnew-1.1.rst
@@ -94,10 +94,14 @@ Default HTTP Exception View
 Minor Feature Additions
 -----------------------
 
-- New request attribute: ``json``. If the request's ``content_type`` is
-  ``application/json``, this attribute will contain the JSON-decoded
-  variant of the request body.  If the request's ``content_type`` is not
-  ``application/json``, this attribute will be ``None``.
+- The :meth:`pyramid.config.Configurator.scan` method has grown a ``**kw``
+  argument.  ``kw`` argument represents a set of keyword arguments to pass to
+  the Venusian ``Scanner`` object created by Pyramid.  (See the
+  :term:`Venusian` documentation for more information about ``Scanner``).
+
+- New request property: ``json_body``. This property will return the
+  JSON-decoded variant of the request body.  If the request body is not
+  well-formed JSON, this property will raise an exception.
 
 - A new value ``http_cache`` can be used as a :term:`view configuration`
   parameter.