From a99e408bd109783561d408ef34c286cdd9b51845 Mon Sep 17 00:00:00 2001
From: Armin Ronacher <armin.ronacher@active-4.com>
Date: Mon, 19 Apr 2010 15:59:16 +0200
Subject: [PATCH] Finished jQuery example documentation.

---
 docs/patterns/jquery.rst                     | 110 ++++++++++++++++++-
 examples/jqueryexample/templates/index.html  |  12 +-
 examples/jqueryexample/templates/layout.html |  10 ++
 3 files changed, 119 insertions(+), 13 deletions(-)
 create mode 100644 examples/jqueryexample/templates/layout.html

diff --git a/docs/patterns/jquery.rst b/docs/patterns/jquery.rst
index cb5aa234..8d00f54e 100644
--- a/docs/patterns/jquery.rst
+++ b/docs/patterns/jquery.rst
@@ -6,7 +6,16 @@ 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.
 
+JSON itself is a very lightweight transport format, very similar to how
+Python primitives (numbers, strings, dicts and lists) look like which is
+widely supported and very easy to parse.  It became popular a few years
+ago and quickly replaced XML as transport format in web applications.
+
+If you have Python 2.6 JSON will work out of the box, in Python 2.5 you
+will have to install the `simplejson`_ library from PyPI.
+
 .. _jQuery: http://jquery.com/
+.. _simplejson: http://pypi.python.org/pypi/simplejson
 
 Loading jQuery
 --------------
@@ -14,15 +23,27 @@ 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):
+to add a script statement to your `head` to load jQuery:
 
 .. 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>
+     url_for('static', filename='jquery.js') }}"></script>
+
+Another method is using Google's `AJAX Libraries API
+<http://code.google.com/apis/ajaxlibs/documentation/>`_ to load jQuery:
+
+.. sourcecode:: html
+
+    <script type=text/javascript
+      src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js"></script>
+
+In this case you don't have to put jQuery into your static folder, it will
+instead be loaded from Google directly.  This has the advantage that your
+website will probably load faster for users if they were to at least one
+other website before using the same jQuery version from Google because it
+will already be in the browser cache.  Downside is that if you don't have
+network connectivity during development jQuery will not load.
 
 Where is My Site?
 -----------------
@@ -57,3 +78,82 @@ inside a `script` block here where different rules apply.
    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.
+
+
+JSON View Functions
+-------------------
+
+Now let's create a server side function that accepts two URL arguments of
+numbers which should be added together and then sent back to the
+application in a JSON object.  This is a really ridiculous example and is
+something you usually would do on the client side alone, but a simple
+example that shows how you would use jQuer and Flask nonetheless::
+
+    from flask import Flask, jsonify, render_template, request
+    app = Flask(__name__)
+
+    @app.route('/_add_numbers')
+    def add_numbers():
+        a = request.args.get('a', 0, type=int)
+        b = request.args.get('b', 0, type=int)
+        return jsonify(result=a + b)
+
+    @app.route('/')
+    def index():
+        return render_template('index.html')
+
+As you can see I also added an `index` method here that renders a
+template.  This template will load jQuery as above and have a little form
+we can add two numbers and a link to trigger the function on the server
+side.
+
+The HTML
+--------
+
+You index.html template either has to extend a `layout.html` template with
+jQuery loaded and the `$SCRIPT_ROOT` variable set, or do that on the top.
+Here the HTML code needed for our little application (`index.html`).
+Notice that we also drop the script directly into the HTML here.  It is
+usually a better idea to have that in a separate script file:
+
+.. sourcecode:: html
+
+    <script type=text/javascript>
+      $(function() {
+        $('a#calculate').bind('click', function() {
+          $.getJSON($SCRIPT_ROOT + '/_add_numbers', {
+            a: $('input[name="a"]').val(),
+            b: $('input[name="b"]').val()
+          }, function(data) {
+            $("#result").text(data.result);
+          });
+          return false;
+        });
+      });
+    </script>
+    <h1>jQuery Example</h1>
+    <p><input type=text size=5 name=a> +
+       <input type=text size=5 name=b> =
+       <span id=result>?</span>
+    <p><a href=# id=calculate>calculate server side</a>
+
+I won't got into detail here about how jQuery works, just a very quick
+explanation of the little bit of code above:
+
+1. ``$(function() { ... })`` specifies code that should run once the
+   browser is done loading the basic parts of the page.
+2. ``#('selector')`` selects an element and lets you operate on it.
+3. ``element.bind('event', func)`` specifies a function that should run
+   when the user clicked on the element.  If that function returns
+   `false`, the default behaviour will not kick in (in this case, navigate
+   to the `#` URL).
+4. ``$.getJSON(url, data, func)`` sends a `GET` request to `url` and will
+   send the contents of the `data` object as query parameters.  Once the
+   data arrived, it will call the given function with the return value as
+   argument.  Note that we can use the `$SCRIPT_ROOT` variable here that
+   we set earlier.
+
+If you don't get the whole picture, download the `sourcecode
+for this example
+<http://github.com/mitsuhiko/flask/tree/master/examples/jqueryexample>`_
+from github.
diff --git a/examples/jqueryexample/templates/index.html b/examples/jqueryexample/templates/index.html
index 6114ae73..0545516d 100644
--- a/examples/jqueryexample/templates/index.html
+++ b/examples/jqueryexample/templates/index.html
@@ -1,12 +1,6 @@
-<!doctype html>
-<title>jQuery Example</title>
-<script type=text/javascript
-  src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js"></script>
-<script type=text/javascript src="{{ url_for('static', filename='app.js')
-  }}"></script>
+{% extends "layout.html" %}
+{% block body %}
 <script type=text/javascript>
-  var $SCRIPT_ROOT = {{ request.script_root|tojson|safe }};
-
   $(function() {
     $('a#calculate').bind('click', function() {
       $.getJSON($SCRIPT_ROOT + '/_add_numbers', {
@@ -15,6 +9,7 @@
       }, function(data) {
         $("#result").text(data.result);
       });
+      return false;
     });
   });
 </script>
@@ -23,3 +18,4 @@
    <input type=text size=5 name=b> =
    <span id=result>?</span>
 <p><a href=# id=calculate>calculate server side</a>
+{% endblock %}
diff --git a/examples/jqueryexample/templates/layout.html b/examples/jqueryexample/templates/layout.html
new file mode 100644
index 00000000..0b5f3a7e
--- /dev/null
+++ b/examples/jqueryexample/templates/layout.html
@@ -0,0 +1,10 @@
+<!doctype html>
+<title>jQuery Example</title>
+<script type=text/javascript
+  src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js"></script>
+<script type=text/javascript src="{{ url_for('static', filename='app.js')
+  }}"></script>
+<script type=text/javascript>
+  var $SCRIPT_ROOT = {{ request.script_root|tojson|safe }};
+</script>
+{% block body %}{% endblock %}