Added JSON Support and started working on jQuery docs

docs/api.rst

@@ -56,12 +56,15 @@ Incoming Request Data
 
    .. attribute:: stream
 
-      If the incoming form data was not encoded with a known encoding (for
-      example it was transmitted as JSON) the data is stored unmodified in
-      this stream for consumption.  For example to read the incoming
-      request data as JSON, one can do the following::
+      If the incoming form data was not encoded with a known mimetype
+      the data is stored unmodified in this stream for consumption.  Most
+      of the time it is a better idea to use :attr:`data` which will give
+      you that data as a string.  The stream only returns the data once.
+      
+   .. attribute:: data
 
-          json_body = simplejson.load(request.stream)
+      Contains the incoming request data as string in case it came with
+      a mimetype Flask does not handle.
 
    .. attribute:: files
 
@@ -106,6 +109,20 @@ Incoming Request Data
       `root_url`    ``http://www.example.com/myapplication/``
       ============= ======================================================
 
+   .. attribute:: is_xhr
+
+      `True` if the request was triggered via a JavaScript
+      `XMLHttpRequest`. This only works with libraries that support the
+      ``X-Requested-With`` header and set it to `XMLHttpRequest`.
+      Libraries that do that are prototype, jQuery and Mochikit and
+      probably some more.
+
+   .. attribute:: json
+
+      Contains the parsed body of the JSON request if the mimetype of
+      the incoming data was `application/json`.  This requires Python 2.6
+      or an installed version of simplejson.
+
 Response Objects
 ----------------
 
@@ -201,6 +218,38 @@ Message Flashing
 
 .. autofunction:: get_flashed_messages
 
+Returning JSON
+--------------
+
+.. autofunction:: jsonify
+
+.. data:: json
+
+    If JSON support is picked up, this will be the module that Flask is
+    using to parse and serialize JSON.  So instead of doing this yourself::
+
+        try:
+            import simplejson as json
+        except ImportError:
+            import json
+
+    You can instead just do this::
+
+        from flask import json
+
+    For usage examples, read the :mod:`json` documentation.
+
+    The :func:`~json.dumps` function of this json module is also available
+    as filter called ``|tojson`` in Jinja2.  Note that inside `script`
+    tags no escaping must take place, so make sure to disable escaping
+    with ``|safe`` if you intend to use it inside `script` tags:
+
+    .. sourcecode:: html+jinja
+
+        <script type=text/javascript>
+            doSomethingWith({{ user.username|tojson|safe }});
+        </script>
+
 Template Rendering
 ------------------
 

docs/patterns/index.rst

@@ -19,3 +19,4 @@ end of the request, the database connection is closed again.
    wtforms
    templateinheritance
    flashing
+   jquery

docs/patterns/jquery.rst

@@ -0,0 +1,59 @@
+AJAX With jQuery
+================
+
+`jQuery`_ is a small JavaScript library commonly used to simplify working
+with the DOM and JavaScript in general.  It is the perfect tool to make
+web applications more dynamic by exchanging JSON between server and
+client.
+
+.. _jQuery: http://jquery.com/
+
+Loading jQuery
+--------------
+
+In order to use jQuery, you have to download it first and place it in the
+static folder of your application and then ensure it's loaded.  Ideally
+you have a layout template that is used for all pages where you just have
+to add two script statements to your `head` section.  One for jQuery, and
+one for your own script (called `app.js` here):
+
+.. sourcecode:: html
+
+   <script type=text/javascript src="{{
+       url_for('static', filename='jquery.js') }}"></script>
+   <script type=text/javascript src="{{
+       url_for('static', filename='app.js') }}"></script>
+
+Where is My Site?
+-----------------
+
+Do you know where your application is?  If you are developing the answer
+is quite simple: it's on localhost port something and directly on the root
+of that server.  But what if you later decide to move your application to
+a different location?  For example to ``http://example.com/myapp``?  On
+the server side this never was a problem because we were using the handy
+:func:`~flask.url_for` function that did could answer that question for
+us, but if we are using jQuery we should better not hardcode the path to
+the application but make that dynamic, so how can we do that?
+
+A simple method would be to add a script tag to our page that sets a
+global variable to the prefix to the root of the application.  Something
+like this:
+
+.. sourcecode:: html+jinja
+
+   <script type=text/javascript>
+     $SCRIPT_ROOT = {{ request.script_root|tojson|safe }};
+   </script>
+
+The ``|safe`` is necessary so that Jinja does not escape the JSON encoded
+string with HTML rules.  Usually this would be necessary, but we are
+inside a `script` block here where different rules apply.
+
+.. admonition:: Information for Pros
+
+   In HTML the `script` tag is declared `CDATA` which means that entities
+   will not be parsed.  Everything until ``</script>`` is handled as script.
+   This also means that there must never be any ``</`` between the script
+   tags.  ``|tojson`` is kindly enough to do the right thing here and
+   escape backslashes for you.