newforms-admin: Merged to [4502]

git-svn-id: http://code.djangoproject.com/svn/django/branches/newforms-admin@4503 bcc190cf-cafb-0310-a4f2-bffc1f526a37

10 files changed, 232 insertions, 13 deletions

diff --git a/docs/contributing.txt b/docs/contributing.txt
index d802d3eaf6..6b2b64f672 100644
--- a/docs/contributing.txt
+++ b/docs/contributing.txt
@@ -484,6 +484,29 @@ Alternatively, you can use a symlink called ``django`` that points to the
 location of the branch's ``django`` package. If you want to switch back, just
 change the symlink to point to the old code.
 
+A third option is to use a `path file`_ (``<something>.pth``) which should
+work on all systems (including Windows, which doesn't have symlinks
+available). First, make sure there are no files, directories or symlinks named
+``django`` in your ``site-packages`` directory. Then create a text file named
+``django.pth`` and save it to your ``site-packages`` directory. That file
+should contain a path to your copy of Django on a single line and optional
+comments. Here is an example that points to multiple branches. Just uncomment
+the line for the branch you want to use ('Trunk' in this example) and make
+sure all other lines are commented::
+
+    # Trunk is a svn checkout of:
+    #   http://code.djangoproject.com/svn/django/trunk/
+    #
+    /path/to/trunk
+    
+    # <branch> is a svn checkout of:
+    #   http://code.djangoproject.com/svn/django/branches/<branch>/
+    #
+    #/path/to/<branch>
+    
+    # On windows a path may look like this:
+    # C:/path/to/<branch>
+
 If you're using Django 0.95 or earlier and installed it using
 ``python setup.py install``, you'll have a directory called something like
 ``Django-0.95-py2.4.egg`` instead of ``django``. In this case, edit the file
@@ -491,6 +514,8 @@ If you're using Django 0.95 or earlier and installed it using
 file. Then copy the branch's version of the ``django`` directory into
 ``site-packages``.
 
+.. _path file: http://docs.python.org/lib/module-site.html
+
 Official releases
 =================
 
diff --git a/docs/django-admin.txt b/docs/django-admin.txt
index 310e8dff0e..cf15168030 100644
--- a/docs/django-admin.txt
+++ b/docs/django-admin.txt
@@ -17,7 +17,12 @@ two things for you before delegating to ``django-admin.py``:
 The ``django-admin.py`` script should be on your system path if you installed
 Django via its ``setup.py`` utility. If it's not on your path, you can find it in
 ``site-packages/django/bin`` within your Python installation. Consider
-symlinking to it from some place on your path, such as ``/usr/local/bin``.
+symlinking it from some place on your path, such as ``/usr/local/bin``.
+
+For Windows users, who do not have symlinking functionality available, you
+can copy ``django-admin.py`` to a location on your existing path or edit the
+``PATH`` settings (under ``Settings - Control Panel - System - Advanced - Environment...``)
+to point to its installed location.
 
 Generally, when working on a single Django project, it's easier to use
 ``manage.py``. Use ``django-admin.py`` with ``DJANGO_SETTINGS_MODULE``, or the
diff --git a/docs/fastcgi.txt b/docs/fastcgi.txt
index b61df49190..1efeaf09cf 100644
--- a/docs/fastcgi.txt
+++ b/docs/fastcgi.txt
@@ -274,7 +274,7 @@ In your Web root directory, add this to a file named ``.htaccess`` ::
 
 Then, create a small script that tells Apache how to spawn your FastCGI
 program. Create a file ``mysite.fcgi`` and place it in your Web directory, and
-be sure to make it executable ::
+be sure to make it executable::
 
     #!/usr/bin/python
     import sys, os
diff --git a/docs/forms.txt b/docs/forms.txt
index 3fa11fea64..fc10e3f17a 100644
--- a/docs/forms.txt
+++ b/docs/forms.txt
@@ -173,10 +173,10 @@ creation view that takes validation into account::
 
         # Check for validation errors
         errors = manipulator.get_validation_errors(new_data)
+        manipulator.do_html2python(new_data)
         if errors:
             return render_to_response('places/errors.html', {'errors': errors})
         else:
-            manipulator.do_html2python(new_data)
             new_place = manipulator.save(new_data)
             return HttpResponse("Place created: %s" % new_place)
 
@@ -229,10 +229,10 @@ Below is the finished view::
 
             # Check for errors.
             errors = manipulator.get_validation_errors(new_data)
+            manipulator.do_html2python(new_data)
 
             if not errors:
                 # No errors. This means we can save the data!
-                manipulator.do_html2python(new_data)
                 new_place = manipulator.save(new_data)
 
                 # Redirect to the object's "edit" page. Always use a redirect
@@ -324,8 +324,8 @@ about editing an existing one? It's shockingly similar to creating a new one::
         if request.method == 'POST':
             new_data = request.POST.copy()
             errors = manipulator.get_validation_errors(new_data)
+            manipulator.do_html2python(new_data)
             if not errors:
-                manipulator.do_html2python(new_data)
                 manipulator.save(new_data)
 
                 # Do a post-after-redirect so that reload works, etc.
@@ -406,8 +406,8 @@ Here's a simple function that might drive the above form::
         if request.method == 'POST':
             new_data = request.POST.copy()
             errors = manipulator.get_validation_errors(new_data)
+            manipulator.do_html2python(new_data)
             if not errors:
-                manipulator.do_html2python(new_data)
 
                 # Send e-mail using new_data here...
 
diff --git a/docs/outputting_pdf.txt b/docs/outputting_pdf.txt
index 464bf7fcb8..bd6ae7a660 100644
--- a/docs/outputting_pdf.txt
+++ b/docs/outputting_pdf.txt
@@ -29,7 +29,7 @@ Test your installation by importing it in the Python interactive interpreter::
 
 If that command doesn't raise any errors, the installation worked.
 
-.. _user guide: http://www.reportlab.org/rsrc/userguide.pdf
+.. _user guide: http://www.reportlab.com/docs/userguide.pdf
 
 Write your view
 ===============
diff --git a/docs/settings.txt b/docs/settings.txt
index cdf440ed6b..b9e46a858c 100644
--- a/docs/settings.txt
+++ b/docs/settings.txt
@@ -827,6 +827,11 @@ manual configuration option (see below), Django will *not* touch the ``TZ``
 environment variable, and it'll be up to you to ensure your processes are
 running in the correct environment.
 
+.. note::
+    Django cannot reliably use alternate time zones in a Windows environment.
+    If you're running Django on Windows, this variable must be set to match the
+    system timezone.
+
 URL_VALIDATOR_USER_AGENT
 ------------------------
 
diff --git a/docs/syndication_feeds.txt b/docs/syndication_feeds.txt
index 72b05ff16a..a64914de3f 100644
--- a/docs/syndication_feeds.txt
+++ b/docs/syndication_feeds.txt
@@ -127,7 +127,7 @@ put into those elements.
       it two template context variables:
 
           * ``{{ obj }}`` -- The current object (one of whichever objects you
-            returned in ``items()``). 
+            returned in ``items()``).
           * ``{{ site }}`` -- A ``django.models.core.sites.Site`` object
             representing the current site. This is useful for
             ``{{ site.domain }}`` or ``{{ site.name }}``.
@@ -478,6 +478,22 @@ This example illustrates all possible attributes and methods for a ``Feed`` clas
 
         categories = ("python", "django") # Hard-coded list of categories.
 
+        # COPYRIGHT NOTICE -- One of the following three is optional. The
+        # framework looks for them in this order.
+
+        def copyright(self, obj):
+            """
+            Takes the object returned by get_object() and returns the feed's
+            copyright notice as a normal Python string.
+            """
+
+        def copyright(self):
+            """
+            Returns the feed's copyright notice as a normal Python string.
+            """
+
+        copyright = 'Copyright (c) 2007, Sally Smith' # Hard-coded copyright notice.
+
         # ITEMS -- One of the following three is required. The framework looks
         # for them in this order.
 
@@ -659,6 +675,23 @@ This example illustrates all possible attributes and methods for a ``Feed`` clas
 
         item_categories = ("python", "django") # Hard-coded categories.
 
+        # ITEM COPYRIGHT NOTICE (only applicable to Atom feeds) -- One of the
+        # following three is optional. The framework looks for them in this
+        # order.
+
+        def item_copyright(self, obj):
+            """
+            Takes an item, as returned by items(), and returns the item's
+            copyright notice as a normal Python string.
+            """
+
+        def item_copyright(self):
+            """
+            Returns the copyright notice for every item in the feed.
+            """
+
+        item_copyright = 'Copyright (c) 2007, Sally Smith' # Hard-coded copyright notice.
+
 
 The low-level framework
 =======================
diff --git a/docs/templates.txt b/docs/templates.txt
index 9f8fe446b4..5a007c13ae 100644
--- a/docs/templates.txt
+++ b/docs/templates.txt
@@ -253,6 +253,16 @@ Here are some tips for working with inheritance:
       if you want to add to the contents of a parent block instead of
       completely overriding it.
 
+    * **New in Django development version:** For extra readability, you can
+      optionally give a *name* to your ``{% endblock %}`` tag. For example::
+
+          {% block content %}
+          ...
+          {% endblock content %}
+
+      In larger templates, this technique helps you see which ``{% block %}``
+      tags are being closed.
+
 Finally, note that you can't define multiple ``{% block %}`` tags with the same
 name in the same template. This limitation exists because a block tag works in
 "both" directions. That is, a block tag doesn't just provide a hole to fill --
@@ -819,6 +829,40 @@ The argument tells which template bit to output:
 
 Note: ``opencomment`` and ``closecomment`` are new in the Django development version.
 
+url
+~~~
+
+**New in Django development version**
+
+**Note that the syntax for this tag may change in the future, as we make it more robust.**
+
+Returns an absolute URL (i.e., a URL without the domain name) matching a given
+view function and optional parameters. This is a way to output links without
+violating the DRY principle by having to hard-code URLs in your templates::
+
+    {% url path.to.some_view arg1,arg2,name1=value1 %}
+
+The first argument is a path to a view function in the format
+``package.package.module.function``. Additional arguments are optional and
+should be comma-separated values that will be used as positional and keyword
+arguments in the URL. All arguments required by the URLconf should be present.
+
+For example, suppose you have a view, ``app_name.client``, whose URLconf takes
+a client ID. The URLconf line might look like this::
+
+    ('^client/(\d+)/$', 'app_name.client')
+
+If this app's URLconf is included into the project's URLconf under a path
+such as this::
+
+    ('^clients/', include('project_name.app_name.urls'))
+
+...then, in a template, you can create a link to this view like this::
+
+    {% url app_name.client client.id %}
+
+The template tag will output the string ``/clients/client/123/``.
+
 widthratio
 ~~~~~~~~~~
 
@@ -1133,6 +1177,16 @@ Truncates a string after a certain number of words.
 
 **Argument:** Number of words to truncate after
 
+truncatewords_html
+~~~~~~~~~~~~~~~~~~
+
+Similar to ``truncatewords``, except that it is aware of HTML tags. Any tags
+that are opened in the string and not closed before the truncation point, are
+closed immediately after the truncation.
+
+This is less efficient than ``truncatewords``, so should only be used when it
+is being passed HTML text.
+
 unordered_list
 ~~~~~~~~~~~~~~
 
diff --git a/docs/templates_python.txt b/docs/templates_python.txt
index 5f9c5bde43..a6b565ed5c 100644
--- a/docs/templates_python.txt
+++ b/docs/templates_python.txt
@@ -801,6 +801,70 @@ Python 2.4 and above::
 If you leave off the ``name`` argument, as in the second example above, Django
 will use the function's name as the tag name.
 
+Passing template variables to the tag
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Although you can pass any number of arguments to a template tag using
+``token.split_contents()``, the arguments are all unpacked as
+string literals. A little more work is required in order to dynamic content (a
+template variable) to a template tag as an argument.
+
+While the previous examples have formatted the current time into a string and
+returned the string, suppose you wanted to pass in a ``DateTimeField`` from an
+object and have the template tag format that date-time::
+
+    <p>This post was last updated at {% format_time blog_entry.date_updated "%Y-%m-%d %I:%M %p" %}.</p>
+
+Initially, ``token.split_contents()`` will return three values:
+
+    1. The tag name ``format_time``.
+    2. The string "blog_entry.date_updated" (without the surrounding quotes).
+    3. The formatting string "%Y-%m-%d %I:%M %p". The return value from
+       ``split_contents()`` will include the leading and trailing quotes for
+       string literals like this.
+
+Now your tag should begin to look like this::
+
+    from django import template
+    def do_format_time(parser, token):
+        try:
+            # split_contents() knows not to split quoted strings.
+            tag_name, date_to_be_formatted, format_string = token.split_contents()
+        except ValueError:
+            raise template.TemplateSyntaxError, "%r tag requires exactly two arguments" % token.contents[0]
+        if not (format_string[0] == format_string[-1] and format_string[0] in ('"', "'")):
+            raise template.TemplateSyntaxError, "%r tag's argument should be in quotes" % tag_name
+        return FormatTimeNode(date_to_be_formatted, format_string[1:-1])
+
+You also have to change the renderer to retrieve the actual contents of the
+``date_updated`` property of the ``blog_entry`` object.  This can be
+accomplished by using the ``resolve_variable()`` function in
+``django.template``. You pass ``resolve_variable()`` the variable name and the
+current context, available in the ``render`` method::
+
+    from django import template
+    from django.template import resolve_variable
+    import datetime
+    class FormatTimeNode(template.Node):
+        def __init__(self, date_to_be_formatted, format_string):
+            self.date_to_be_formatted = date_to_be_formatted
+            self.format_string = format_string
+        
+        def render(self, context):
+            try:
+                actual_date = resolve_variable(self.date_to_be_formatted, context)
+                return actual_date.strftime(self.format_string)
+            except VariableDoesNotExist:
+                return ''
+
+``resolve_variable`` will try to resolve ``blog_entry.date_updated`` and then
+format it accordingly.
+
+.. note::
+    The ``resolve_variable()`` function will throw a ``VariableDoesNotExist``
+    exception if it cannot resolve the string passed to it in the current
+    context of the page.
+
 Shortcut for simple tags
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/testing.txt b/docs/testing.txt
index e7c1a3b161..cab31ed63b 100644
--- a/docs/testing.txt
+++ b/docs/testing.txt
@@ -198,11 +198,6 @@ used as test conditions.
 .. _Twill: http://twill.idyll.org/
 .. _Selenium: http://www.openqa.org/selenium/
 
-The Test Client is stateful; if a cookie is returned as part of a response,
-that cookie is provided as part of the next request issued to that Client
-instance. Expiry policies for these cookies are not followed; if you want 
-a cookie to expire, either delete it manually from ``client.cookies``, or 
-create a new Client instance (which will effectively delete all cookies).
 
 Making requests
 ~~~~~~~~~~~~~~~
@@ -296,6 +291,44 @@ for testing purposes:
 
 .. _RFC2616: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
 
+Exceptions
+~~~~~~~~~~
+
+If you point the Test Client at a view that raises an exception, that exception
+will be visible in the test case. You can then use a standard ``try...catch`` 
+block, or ``unittest.TestCase.assertRaises()`` to test for exceptions.
+
+The only exceptions that are not visible in a Test Case are ``Http404``, 
+``PermissionDenied`` and ``SystemExit``. Django catches these exceptions 
+internally and converts them into the appropriate HTTP responses codes.
+
+Persistent state
+~~~~~~~~~~~~~~~~
+
+The Test Client is stateful; if a cookie is returned as part of a response,
+that cookie is provided as part of the next request issued by that Client
+instance. Expiry policies for these cookies are not followed; if you want 
+a cookie to expire, either delete it manually or create a new Client 
+instance (which will effectively delete all cookies).
+
+There are two properties of the Test Client which are used to store persistent
+state information. If necessary, these properties can be interrogated as
+part of a test condition.
+
+    ===============  ==========================================================
+    Property         Description
+    ===============  ==========================================================
+    ``cookies``      A Python ``SimpleCookie`` object, containing the current
+                     values of all the client cookies.
+
+    ``session``      A dictionary-like object containing session information.
+                     See the `session documentation`_ for full details.
+
+.. _`session documentation`: ../sessions/
+                     
+Example
+~~~~~~~
+
 The following is a simple unit test using the Test Client::
     
     import unittest