Merge branch 'master' of github.com:Pylons/pyramid

1 files changed, 103 insertions, 0 deletions

diff --git a/docs/quick_tutorial/json.rst b/docs/quick_tutorial/json.rst
new file mode 100644
index 000000000..ece8a61c0
--- /dev/null
+++ b/docs/quick_tutorial/json.rst
@@ -0,0 +1,103 @@
+.. _qtut_json:
+
+========================================
+14: Ajax Development With JSON Renderers
+========================================
+
+Modern web apps are more than rendered HTML. Dynamic pages now use
+JavaScript to update the UI in the browser by requesting server data as
+JSON. Pyramid supports this with a *JSON renderer*.
+
+Background
+==========
+
+As we saw in :doc:`templating`, view declarations can specify a
+renderer. Output from the view is then run through the renderer,
+which generates and returns the ``Response``. We first used a Chameleon
+renderer, then a Jinja2 renderer.
+
+Renderers aren't limited, however, to templates that generate HTML.
+Pyramid supplies a JSON renderer which takes Python data,
+serializes it to JSON, and performs some other functions such as
+setting the content type. In fact, you can write your own renderer (or
+extend a built-in renderer) containing custom logic for your unique
+application.
+
+Steps
+=====
+
+#. First we copy the results of the ``view_classes`` step:
+
+   .. code-block:: bash
+
+    $ cd ..; cp -r view_classes json; cd json
+    $ $VENV/bin/python setup.py develop
+
+#. We add a new route for ``hello_json`` in
+   ``json/tutorial/__init__.py``:
+
+   .. literalinclude:: json/tutorial/__init__.py
+    :linenos:
+
+#. Rather than implement a new view, we will "stack" another decorator
+   on the ``hello`` view:
+
+   .. literalinclude:: json/tutorial/views.py
+    :linenos:
+
+#. We need a new functional test at the end of
+   ``json/tutorial/tests.py``:
+
+   .. literalinclude:: json/tutorial/tests.py
+    :linenos:
+
+#. Run the tests:
+
+   .. code-block:: bash
+
+    $ $VENV/bin/nosetests tutorial
+
+#. Run your Pyramid application with:
+
+   .. code-block:: bash
+
+    $ $VENV/bin/pserve development.ini --reload
+
+#. Open http://localhost:6543/howdy.json in your browser and you
+   will see the resulting JSON response.
+
+Analysis
+========
+
+Earlier we changed our view functions and methods to return Python
+data. This change to a data-oriented view layer made test writing
+easier, decoupling the templating from the view logic.
+
+Since Pyramid has a JSON renderer as well as the templating renderers,
+it is an easy step to return JSON. In this case we kept the exact same
+view and arranged to return a JSON encoding of the view data. We did
+this by:
+
+- Adding a route to map ``/howdy.json`` to a route name
+
+- Providing a ``@view_config`` that associated that route name with an
+  existing view
+
+- *overriding* the view defaults in the view config that mentions the 
+  ``hello_json`` route, so that when the route is matched, we use the JSON 
+  renderer rather than the ``home.pt`` template renderer that would otherwise 
+  be used.
+
+In fact, for pure Ajax-style web applications, we could re-use the existing
+route by using Pyramid's view predicates to match on the
+``Accepts:`` header sent by modern Ajax implementation.
+
+Pyramid's JSON renderer uses the base Python JSON encoder,
+thus inheriting its strengths and weaknesses. For example,
+Python can't natively JSON encode DateTime objects. There are a number
+of solutions for this in Pyramid, including extending the JSON renderer
+with a custom renderer.
+
+.. seealso:: :ref:`views_which_use_a_renderer`,
+   :ref:`json_renderer`, and
+   :ref:`adding_and_overriding_renderers`