From b1b92284f496800a4dfd2cea72cb9be07ba8661c Mon Sep 17 00:00:00 2001 From: Paul Everitt Date: Fri, 13 Sep 2013 16:52:14 -0400 Subject: First cut at import of quick tutorial. --- docs/quick_tutorial/json.rst | 101 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 101 insertions(+) create mode 100644 docs/quick_tutorial/json.rst (limited to 'docs/quick_tutorial/json.rst') diff --git a/docs/quick_tutorial/json.rst b/docs/quick_tutorial/json.rst new file mode 100644 index 000000000..213de8364 --- /dev/null +++ b/docs/quick_tutorial/json.rst @@ -0,0 +1,101 @@ +======================================== +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 + + (env27)$ cd ..; cp -r view_classes json; cd json + (env27)$ 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 + + (env27)$ nosetests tutorial + +#. Run your Pyramid application with: + + .. code-block:: bash + + (env27)$ 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:`pyramid:views_which_use_a_renderer`, + :ref:`pyramid:json_renderer`, and + :ref:`pyramid:adding_and_overriding_renderers` -- cgit v1.2.3 From 4042c772c8043ac96a22db439a736fec9ea2aafa Mon Sep 17 00:00:00 2001 From: Paul Everitt Date: Fri, 13 Sep 2013 17:09:35 -0400 Subject: All the references re-wired. --- docs/quick_tutorial/json.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/quick_tutorial/json.rst') diff --git a/docs/quick_tutorial/json.rst b/docs/quick_tutorial/json.rst index 213de8364..f08db6849 100644 --- a/docs/quick_tutorial/json.rst +++ b/docs/quick_tutorial/json.rst @@ -96,6 +96,6 @@ 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:`pyramid:views_which_use_a_renderer`, - :ref:`pyramid:json_renderer`, and - :ref:`pyramid:adding_and_overriding_renderers` +.. seealso:: :ref:`views_which_use_a_renderer`, + :ref:`json_renderer`, and + :ref:`adding_and_overriding_renderers` -- cgit v1.2.3 From 0a784868bdbc3a0eb226ed00e8d89cda9d181ec5 Mon Sep 17 00:00:00 2001 From: Paul Everitt Date: Fri, 13 Sep 2013 17:11:42 -0400 Subject: Fix naming of virtualenv prefix. --- docs/quick_tutorial/json.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/quick_tutorial/json.rst') diff --git a/docs/quick_tutorial/json.rst b/docs/quick_tutorial/json.rst index f08db6849..4727a102a 100644 --- a/docs/quick_tutorial/json.rst +++ b/docs/quick_tutorial/json.rst @@ -28,8 +28,8 @@ Steps .. code-block:: bash - (env27)$ cd ..; cp -r view_classes json; cd json - (env27)$ python setup.py develop + (env)$ cd ..; cp -r view_classes json; cd json + (env)$ python setup.py develop #. We add a new route for ``hello_json`` in ``json/tutorial/__init__.py``: @@ -53,13 +53,13 @@ Steps .. code-block:: bash - (env27)$ nosetests tutorial + (env)$ nosetests tutorial #. Run your Pyramid application with: .. code-block:: bash - (env27)$ pserve development.ini --reload + (env)$ pserve development.ini --reload #. Open ``http://localhost:6543/howdy.json`` in your browser and you will see the resulting JSON response. -- cgit v1.2.3 From b0b28ede912c817a62a84b97c332e39eda02d166 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Mon, 16 Sep 2013 02:14:53 +0200 Subject: s/env/venv just for sake of consistency --- docs/quick_tutorial/json.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/quick_tutorial/json.rst') diff --git a/docs/quick_tutorial/json.rst b/docs/quick_tutorial/json.rst index 4727a102a..2df76795c 100644 --- a/docs/quick_tutorial/json.rst +++ b/docs/quick_tutorial/json.rst @@ -28,8 +28,8 @@ Steps .. code-block:: bash - (env)$ cd ..; cp -r view_classes json; cd json - (env)$ python setup.py develop + (venv)$ cd ..; cp -r view_classes json; cd json + (venv)$ python setup.py develop #. We add a new route for ``hello_json`` in ``json/tutorial/__init__.py``: @@ -53,13 +53,13 @@ Steps .. code-block:: bash - (env)$ nosetests tutorial + (venv)$ nosetests tutorial #. Run your Pyramid application with: .. code-block:: bash - (env)$ pserve development.ini --reload + (venv)$ pserve development.ini --reload #. Open ``http://localhost:6543/howdy.json`` in your browser and you will see the resulting JSON response. -- cgit v1.2.3 From d749bf4c987c4ab90bd5f89326e7d4059e4f47b3 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Mon, 16 Sep 2013 02:18:11 +0200 Subject: make example links clickable, for convenience --- docs/quick_tutorial/json.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/quick_tutorial/json.rst') diff --git a/docs/quick_tutorial/json.rst b/docs/quick_tutorial/json.rst index 2df76795c..2d5c93106 100644 --- a/docs/quick_tutorial/json.rst +++ b/docs/quick_tutorial/json.rst @@ -61,7 +61,7 @@ Steps (venv)$ pserve development.ini --reload -#. Open ``http://localhost:6543/howdy.json`` in your browser and you +#. Open http://localhost:6543/howdy.json in your browser and you will see the resulting JSON response. Analysis -- cgit v1.2.3 From 187104fd81418beeb51592913041d9751bafe08d Mon Sep 17 00:00:00 2001 From: Paul Everitt Date: Wed, 25 Sep 2013 09:27:43 -0400 Subject: Quick Tutorial: Improve the setup instructions (adapted from Steve Piercy's work), particularly for Windows. Change all the steps to use $VENV/bin prefixes on commands (don't presume that they have done source env/bin/activate). --- docs/quick_tutorial/json.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/quick_tutorial/json.rst') diff --git a/docs/quick_tutorial/json.rst b/docs/quick_tutorial/json.rst index 2d5c93106..c92e4eadd 100644 --- a/docs/quick_tutorial/json.rst +++ b/docs/quick_tutorial/json.rst @@ -28,8 +28,8 @@ Steps .. code-block:: bash - (venv)$ cd ..; cp -r view_classes json; cd json - (venv)$ python setup.py develop + $ 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``: @@ -53,13 +53,13 @@ Steps .. code-block:: bash - (venv)$ nosetests tutorial + $ $VENV/bin/nosetests tutorial #. Run your Pyramid application with: .. code-block:: bash - (venv)$ pserve development.ini --reload + $ $VENV/bin/pserve development.ini --reload #. Open http://localhost:6543/howdy.json in your browser and you will see the resulting JSON response. -- cgit v1.2.3 From b731b5fca253d9d95b3307490aa585e194676c01 Mon Sep 17 00:00:00 2001 From: Paul Everitt Date: Thu, 26 Sep 2013 17:41:44 -0400 Subject: Quick Tour: shorten the setup part and point to Quick Tutorial Requirements for more explanation. Cross link each Quick Tour section with its Quick Tutorial match. --- docs/quick_tutorial/json.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/quick_tutorial/json.rst') diff --git a/docs/quick_tutorial/json.rst b/docs/quick_tutorial/json.rst index c92e4eadd..ece8a61c0 100644 --- a/docs/quick_tutorial/json.rst +++ b/docs/quick_tutorial/json.rst @@ -1,3 +1,5 @@ +.. _qtut_json: + ======================================== 14: Ajax Development With JSON Renderers ======================================== -- cgit v1.2.3