[soc2009/multidb] Merged up to trunk r11756.

git-svn-id: http://code.djangoproject.com/svn/django/branches/soc2009/multidb@11758 bcc190cf-cafb-0310-a4f2-bffc1f526a37

docs/intro/install.txt

@@ -12,7 +12,7 @@ Install Python
 --------------
 
 Being a Python Web framework, Django requires Python. It works with any Python
-version from 2.3 to 2.6 (due to backwards
+version from 2.4 to 2.6 (due to backwards
 incompatibilities in Python 3.0, Django does not currently work with
 Python 3.0; see :ref:`the Django FAQ <faq-install>` for more
 information on supported Python versions and the 3.0 transition), but we recommend installing Python 2.5 or later. If you do so, you won't need to set up a database just yet: Python 2.5 or later includes a lightweight database called SQLite_.

docs/intro/tutorial01.txt

@@ -282,6 +282,7 @@ That'll create a directory :file:`polls`, which is laid out like this::
     polls/
         __init__.py
         models.py
+        tests.py
         views.py
 
 This directory structure will house the poll application.

docs/intro/tutorial02.txt

@@ -34,11 +34,11 @@ activate the admin site for your installation, do these three things:
     * Run ``python manage.py syncdb``. Since you have added a new application
       to :setting:`INSTALLED_APPS`, the database tables need to be updated.
 
-    * Edit your ``mysite/urls.py`` file and uncomment the lines below the
-      "Uncomment the next two lines..." comment. This file is a URLconf;
-      we'll dig into URLconfs in the next tutorial. For now, all you need to
-      know is that it maps URL roots to applications. In the end, you should
-      have a ``urls.py`` file that looks like this:
+    * Edit your ``mysite/urls.py`` file and uncomment the lines that reference
+      the admin -- there are three lines in total to uncomment. This file is a
+      URLconf; we'll dig into URLconfs in the next tutorial. For now, all you
+      need to know is that it maps URL roots to applications. In the end, you
+      should have a ``urls.py`` file that looks like this:
 
     .. versionchanged:: 1.1
         The method for adding admin urls has changed in Django 1.1.

docs/intro/tutorial03.txt

@@ -171,15 +171,23 @@ and put the following Python code in it::
 This is the simplest view possible. Go to "/polls/" in your browser, and you
 should see your text.
 
-Now add the following view. It's slightly different, because it takes an
-argument (which, remember, is passed in from whatever was captured by the
-regular expression in the URLconf)::
+Now lets add a few more views. These views are slightly different, because
+they take an argument (which, remember, is passed in from whatever was
+captured by the regular expression in the URLconf)::
 
     def detail(request, poll_id):
         return HttpResponse("You're looking at poll %s." % poll_id)
 
-Take a look in your browser, at "/polls/34/". It'll display whatever ID you
-provide in the URL.
+    def results(request, poll_id):
+        return HttpResponse("You're looking at the results of poll %s." % poll_id)
+
+    def vote(request, poll_id):
+        return HttpResponse("You're voting on poll %s." % poll_id)
+
+Take a look in your browser, at "/polls/34/". It'll run the `detail()` method
+and display whatever ID you provide in the URL. Try "/polls/34/results/" and
+"/polls/34/vote/" too -- these will display the placeholder results and voting
+pages.
 
 Write views that actually do something
 ======================================
@@ -467,10 +475,10 @@ Copy the file ``mysite/urls.py`` to ``mysite/polls/urls.py``. Then, change
 ``mysite/urls.py`` to remove the poll-specific URLs and insert an
 :func:`~django.conf.urls.defaults.include`::
 
-    ...
+    # ...
     urlpatterns = patterns('',
         (r'^polls/', include('mysite.polls.urls')),
-        ...
+        # ...
 
 :func:`~django.conf.urls.defaults.include`, simply, references another URLconf.
 Note that the regular expression doesn't have a ``$`` (end-of-string match

docs/intro/tutorial04.txt

@@ -21,6 +21,7 @@ tutorial, so that the template contains an HTML ``<form>`` element:
     {% if error_message %}<p><strong>{{ error_message }}</strong></p>{% endif %}
 
     <form action="/polls/{{ poll.id }}/vote/" method="post">
+    {% csrf_token %}
     {% for choice in poll.choice_set.all %}
         <input type="radio" name="choice" id="choice{{ forloop.counter }}" value="{{ choice.id }}" />
         <label for="choice{{ forloop.counter }}">{{ choice.choice }}</label><br />
@@ -46,17 +47,41 @@ A quick rundown:
     * ``forloop.counter`` indicates how many times the :ttag:`for` tag has gone
       through its loop
 
+    * Since we are creating a POST form (which can have the effect of modifying
+      data), we unfortunately need to worry about Cross Site Request Forgeries.
+      Thankfully, you don't have to worry too hard, because Django comes with
+      very easy-to-use system for protecting against it.  In short, all POST
+      forms that are targetted at internal URLs need the ``{% csrf_token %}``
+      template tag adding.
+
+The ``{% csrf_token %}`` tag requires information from the request object, which
+is not normally accessible from within the template context.  To fix this, a
+small adjustment needs to be made to the ``detail`` view, so that it looks like
+the following::
+
+    from django.template import RequestContext
+    # ...
+    def detail(request, poll_id):
+        p = get_object_or_404(Poll, pk=poll_id)
+        return render_to_response('polls/detail.html', {'poll': p},
+                                   context_instance=RequestContext(request))
+
+The details of how this works are explained in the documentation for
+:ref:`RequestContext <subclassing-context-requestcontext>`.
+
 Now, let's create a Django view that handles the submitted data and does
 something with it. Remember, in :ref:`Tutorial 3 <intro-tutorial03>`, we
 created a URLconf for the polls application that includes this line::
 
     (r'^(?P<poll_id>\d+)/vote/$', 'vote'),
 
-So let's create a ``vote()`` function in ``mysite/polls/views.py``::
+We also created a dummy implementation of the ``vote()`` function. Let's
+create a real version. Add the following to ``mysite/polls/views.py``::
 
     from django.shortcuts import get_object_or_404, render_to_response
-    from django.http import HttpResponseRedirect
+    from django.http import HttpResponseRedirect, HttpResponse
     from django.core.urlresolvers import reverse
+    from django.template import RequestContext
     from mysite.polls.models import Choice, Poll
     # ...
     def vote(request, poll_id):
@@ -68,7 +93,7 @@ So let's create a ``vote()`` function in ``mysite/polls/views.py``::
             return render_to_response('polls/detail.html', {
                 'poll': p,
                 'error_message': "You didn't select a choice.",
-            })
+            }, context_instance=RequestContext(request))
         else:
             selected_choice.votes += 1
             selected_choice.save()