newforms-admin: Merged to [5300]

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

7 files changed, 215 insertions, 34 deletions

diff --git a/docs/contributing.txt b/docs/contributing.txt
index d05c166b37..31409f27bd 100644
--- a/docs/contributing.txt
+++ b/docs/contributing.txt
@@ -279,6 +279,15 @@ Please follow these coding standards when writing code for inclusion in Django:
     * Mark all strings for internationalization; see the `i18n documentation`_
       for details.
 
+    * Please don't put your name in the code you contribute. Our policy is to
+      keep contributors' names in the ``AUTHORS`` file distributed with Django
+      -- not scattered throughout the codebase itself. Feel free to include a
+      change to the ``AUTHORS`` file in your patch if you make more than a
+      single trivial change.
+
+Template style
+--------------
+
     * In Django template code, put one (and only one) space between the curly
       brackets and the tag contents.
 
@@ -290,6 +299,9 @@ Please follow these coding standards when writing code for inclusion in Django:
 
           {{foo}}
 
+View style
+----------
+
     * In Django views, the first parameter in a view function should be called
       ``request``.
 
@@ -303,11 +315,72 @@ Please follow these coding standards when writing code for inclusion in Django:
           def my_view(req, foo):
               # ...
 
-    * Please don't put your name in the code you contribute. Our policy is to
-      keep contributors' names in the ``AUTHORS`` file distributed with Django
-      -- not scattered throughout the codebase itself. Feel free to include a
-      change to the ``AUTHORS`` file in your patch if you make more than a
-      single trivial change.
+Model style
+-----------
+
+    * Field names should be all lowercase, using underscores instead of
+      camelCase.
+
+      Do this::
+
+          class Person(models.Model):
+              first_name = models.CharField(maxlength=20)
+              last_name = models.CharField(maxlength=40)
+
+      Don't do this::
+
+          class Person(models.Model):
+              FirstName = models.CharField(maxlength=20)
+              Last_Name = models.CharField(maxlength=40)
+
+    * The ``class Meta`` should appear *after* the fields are defined, with
+      a single blank line separating the fields and the class definition.
+
+      Do this::
+
+          class Person(models.Model):
+              first_name = models.CharField(maxlength=20)
+              last_name = models.CharField(maxlength=40)
+
+              class Meta:
+                  verbose_name_plural = 'people'
+
+      Don't do this::
+
+          class Person(models.Model):
+              first_name = models.CharField(maxlength=20)
+              last_name = models.CharField(maxlength=40)
+              class Meta:
+                  verbose_name_plural = 'people'
+
+      Don't do this, either::
+
+          class Person(models.Model):
+              class Meta:
+                  verbose_name_plural = 'people'
+
+              first_name = models.CharField(maxlength=20)
+              last_name = models.CharField(maxlength=40)
+
+    * The order of model inner classes and standard methods should be as
+      follows (noting that these are not all required):
+
+        * All database fields
+        * ``class Meta``
+        * ``class Admin``
+        * ``def __str__()``
+        * ``def save()``
+        * ``def get_absolute_url()``
+        * Any custom methods
+
+    * If ``choices`` is defined for a given model field, define the choices as
+      a tuple of tuples, with an all-uppercase name, either near the top of the
+      model module or just above the model class. Example::
+
+          GENDER_CHOICES = (
+              ('M', 'Male'),
+              ('F', 'Female'),
+          )
 
 Committing code
 ===============
diff --git a/docs/db-api.txt b/docs/db-api.txt
index 9d2f09daf3..de612e0e3d 100644
--- a/docs/db-api.txt
+++ b/docs/db-api.txt
@@ -143,8 +143,8 @@ or ``UPDATE`` SQL statements. Specifically, when you call ``save()``, Django
 follows this algorithm:
 
     * If the object's primary key attribute is set to a value that evaluates to
-      ``True`` (i.e., a value other than ``None`` or the empty string), Django 
-      executes a ``SELECT`` query to determine whether a record with the given 
+      ``True`` (i.e., a value other than ``None`` or the empty string), Django
+      executes a ``SELECT`` query to determine whether a record with the given
       primary key already exists.
     * If the record with the given primary key does already exist, Django
       executes an ``UPDATE`` query.
@@ -525,19 +525,19 @@ Examples::
     [datetime.datetime(2005, 3, 20), datetime.datetime(2005, 2, 20)]
     >>> Entry.objects.filter(headline__contains='Lennon').dates('pub_date', 'day')
     [datetime.datetime(2005, 3, 20)]
-    
+
 ``none()``
 ~~~~~~~~~~
 
 **New in Django development version**
 
-Returns an ``EmptyQuerySet`` -- a ``QuerySet`` that always evaluates to 
+Returns an ``EmptyQuerySet`` -- a ``QuerySet`` that always evaluates to
 an empty list. This can be used in cases where you know that you should
 return an empty result set and your caller is expecting a ``QuerySet``
 object (instead of returning an empty list, for example.)
 
 Examples::
-    
+
     >>> Entry.objects.none()
     []
 
@@ -610,7 +610,7 @@ follow::
     c = p.hometown       # Requires a database call.
 
 The ``depth`` argument is new in the Django development version.
-    
+
 ``extra(select=None, where=None, params=None, tables=None)``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -1136,7 +1136,7 @@ such as January 3, July 3, etc.
 isnull
 ~~~~~~
 
-Takes either ``True`` or ``False``, which correspond to SQL queries of 
+Takes either ``True`` or ``False``, which correspond to SQL queries of
 ``IS NULL`` and ``IS NOT NULL``, respectively.
 
 Example::
@@ -1149,10 +1149,10 @@ SQL equivalent::
 
 .. admonition:: ``__isnull=True`` vs ``__exact=None``
 
-    There is an important difference between ``__isnull=True`` and 
+    There is an important difference between ``__isnull=True`` and
     ``__exact=None``. ``__exact=None`` will *always* return an empty result
-    set, because SQL requires that no value is equal to ``NULL``. 
-    ``__isnull`` determines if the field is currently holding the value 
+    set, because SQL requires that no value is equal to ``NULL``.
+    ``__isnull`` determines if the field is currently holding the value
     of ``NULL`` without performing a comparison.
 
 search
@@ -1181,7 +1181,7 @@ The pk lookup shortcut
 ----------------------
 
 For convenience, Django provides a ``pk`` lookup type, which stands for
-"primary_key". 
+"primary_key".
 
 In the example ``Blog`` model, the primary key is the ``id`` field, so these
 three statements are equivalent::
@@ -1190,14 +1190,14 @@ three statements are equivalent::
     Blog.objects.get(id=14) # __exact is implied
     Blog.objects.get(pk=14) # pk implies id__exact
 
-The use of ``pk`` isn't limited to ``__exact`` queries -- any query term 
+The use of ``pk`` isn't limited to ``__exact`` queries -- any query term
 can be combined with ``pk`` to perform a query on the primary key of a model::
 
     # Get blogs entries  with id 1, 4 and 7
     Blog.objects.filter(pk__in=[1,4,7])
     # Get all blog entries with id > 14
-    Blog.objects.filter(pk__gt=14) 
-    
+    Blog.objects.filter(pk__gt=14)
+
 ``pk`` lookups also work across joins. For example, these three statements are
 equivalent::
 
@@ -1754,19 +1754,19 @@ get_object_or_404()
 -------------------
 
 One common idiom to use ``get()`` and raise ``Http404`` if the
-object doesn't exist. This idiom is captured by ``get_object_or_404()``. 
-This function takes a Django model as its first argument and an 
-arbitrary number of keyword arguments, which it passes to the manager's 
+object doesn't exist. This idiom is captured by ``get_object_or_404()``.
+This function takes a Django model as its first argument and an
+arbitrary number of keyword arguments, which it passes to the manager's
 ``get()`` function. It raises ``Http404`` if the object doesn't
-exist. For example:: 
-    
+exist. For example::
+
     # Get the Entry with a primary key of 3
     e = get_object_or_404(Entry, pk=3)
 
-When you provide a model to this shortcut function, the default manager 
-is used to execute the underlying ``get()`` query. If you don't want to 
-use the default manager, or you want to search a list of related objects, 
-you can provide ``get_object_or_404()`` with a manager object, instead. 
+When you provide a model to this shortcut function, the default manager
+is used to execute the underlying ``get()`` query. If you don't want to
+use the default manager, or if you want to search a list of related objects,
+you can provide ``get_object_or_404()`` with a manager object instead.
 For example::
 
     # Get the author of blog instance `e` with a name of 'Fred'
@@ -1779,8 +1779,8 @@ For example::
 get_list_or_404()
 -----------------
 
-``get_list_or_404`` behaves the same was as ``get_object_or_404()`` 
--- except the it uses using ``filter()`` instead of ``get()``. It raises 
+``get_list_or_404`` behaves the same way as ``get_object_or_404()``
+-- except that it uses ``filter()`` instead of ``get()``. It raises
 ``Http404`` if the list is empty.
 
 Falling back to raw SQL
diff --git a/docs/install.txt b/docs/install.txt
index 6be52aab0d..c3ccd27f76 100644
--- a/docs/install.txt
+++ b/docs/install.txt
@@ -11,8 +11,8 @@ Being a Python Web framework, Django requires Python.
 
 It works with any Python version 2.3 and higher.
 
-Get Python at www.python.org. If you're running Linux or Mac OS X, you probably
-already have it installed.
+Get Python at http://www.python.org. If you're running Linux or Mac OS X, you
+probably already have it installed.
 
 Install Apache and mod_python
 =============================
diff --git a/docs/model-api.txt b/docs/model-api.txt
index 961269aebd..1125d2810f 100644
--- a/docs/model-api.txt
+++ b/docs/model-api.txt
@@ -1759,6 +1759,15 @@ But this template code is good::
 
     <a href="{{ object.get_absolute_url }}">{{ object.name }}</a>
 
+.. note::
+    The string you return from ``get_absolute_url()`` must contain only ASCII
+    characters (required by the URI spec, `RFC 2396`_) that have been
+    URL-encoded, if necessary. Code and templates using ``get_absolute_url()``
+    should be able to use the result directly without needing to do any
+    further processing.
+
+.. _RFC 2396: http://www.ietf.org/rfc/rfc2396.txt
+
 The ``permalink`` decorator
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/newforms.txt b/docs/newforms.txt
index ed43670960..5516f60683 100644
--- a/docs/newforms.txt
+++ b/docs/newforms.txt
@@ -602,6 +602,102 @@ when printed::
     >>> str(f['subject'].errors)
     ''
 
+Using forms in views and templates
+----------------------------------
+
+Let's put this all together and use the ``ContactForm`` example in a Django
+view and template. This example view displays the contact form by default and
+validates/processes it if accessed via a POST request::
+
+    def contact(request):
+        if request.method == 'POST':
+            form = ContactForm(request.POST)
+            if form.is_valid():
+                # Do form processing here...
+                return HttpResponseRedirect('/url/on_success/')
+        else:
+            form = ContactForm()
+        return render_to_response('contact.html', {'form': form})
+
+Simple template output
+~~~~~~~~~~~~~~~~~~~~~~
+
+The template, ``contact.html``, is responsible for displaying the form as HTML.
+To do this, we can use the techniques outlined in the "Outputting forms as HTML"
+section above.
+
+The simplest way to display a form's HTML is to use the variable on its own,
+like this::
+
+    <form method="post">
+    <table>{{ form }}</table>
+    <input type="submit" />
+    </form>
+
+The above template code will display the form as an HTML table, using the
+``form.as_table()`` method explained previously. This works because Django's
+template system displays an object's ``__str__()`` value, and the ``Form``
+class' ``__str__()`` method calls its ``as_table()`` method.
+
+The following is equivalent but a bit more explicit::
+
+    <form method="post">
+    <table>{{ form.as_table }}</table>
+    <input type="submit" />
+    </form>
+
+``form.as_ul`` and ``form.as_p`` are also available, as you may expect.
+
+Note that in the above two examples, we included the ``<form>``, ``<table>``
+``<input type="submit" />``, ``</table>`` and ``</form>`` tags. The form
+convenience methods (``as_table()``, ``as_ul()`` and ``as_p()``) do not include
+that HTML.
+
+Complex template output
+~~~~~~~~~~~~~~~~~~~~~~~
+
+As we've stressed several times, the ``as_table()``, ``as_ul()`` and ``as_p()``
+methods are just shortcuts for the common case. You can also work with the
+individual fields for complete template control over the form's design.
+
+The easiest way is to iterate over the form's fields, with
+``{% for field in form %}``. For example::
+
+    <form method="post">
+    <dl>
+    {% for field in form %}
+        <dt>{{ field.label }}</dt>
+        <dd>{{ field }}</dd>
+        {% if field.help_text %}<dd>{{ field.help_text }}</dd>{% endif %}
+        {% if field.errors %}<dd class="myerrors">{{ field.errors }}</dd>{% endif %}
+    {% endfor %}
+    </dl>
+    <input type="submit" />
+    </form>
+
+This iteration technique is useful if you want to apply the same HTML
+formatting to each field, or if you don't know the names of the form fields
+ahead of time. Note that the fields will be listed in the order in which
+they're defined in the ``Form`` class.
+
+Alternatively, you can arrange the form's fields explicitly, by name. Do that
+by accessing ``{{ form.fieldname }}``, where ``fieldname`` is the field's name.
+For example::
+
+    <form method="post">
+    <ul class="myformclass">
+        <li>{{ form.sender.label }} {{ form.sender.label }}</li>
+        <li class="helptext">{{ form.sender.help_text }}</li>
+        {% if form.sender.errors %}<ul class="errorlist">{{ form.sender.errors }}</dd>{% endif %}
+
+        <li>{{ form.subject.label }} {{ form.subject.label }}</li>
+        <li class="helptext">{{ form.subject.help_text }}</li>
+        {% if form.subject.errors %}<ul class="errorlist">{{ form.subject.errors }}</dd>{% endif %}
+
+        ...
+    </ul>
+    </form>
+
 Subclassing forms
 -----------------
 
diff --git a/docs/settings.txt b/docs/settings.txt
index 72c6e4ce54..bf0a9f85f6 100644
--- a/docs/settings.txt
+++ b/docs/settings.txt
@@ -1055,7 +1055,7 @@ You can tell Django to stop reporting particular 404s by tweaking the
 tuple of strings. For example::
 
     IGNORABLE_404_ENDS = ('.php', '.cgi')
-    IGNORABLE_404_STARTS = ('/phpmyadmin/')
+    IGNORABLE_404_STARTS = ('/phpmyadmin/',)
 
 In this example, a 404 to any URL ending with ``.php`` or ``.cgi`` will *not*
 be reported. Neither will any URL starting with ``/phpmyadmin/``.
diff --git a/docs/syndication_feeds.txt b/docs/syndication_feeds.txt
index d9d4f53b88..2a03e6d5a6 100644
--- a/docs/syndication_feeds.txt
+++ b/docs/syndication_feeds.txt
@@ -146,7 +146,10 @@ put into those elements.
       exist, it tries calling a method ``item_link()`` in the ``Feed`` class,
       passing it a single parameter, ``item``, which is the object itself.
       Both ``get_absolute_url()`` and ``item_link()`` should return the item's
-      URL as a normal Python string.
+      URL as a normal Python string. As with ``get_absolute_url()``, the
+      result of ``item_link()`` will be included directly in the URL, so you
+      are responsible for doing all necessary URL quoting and conversion to
+      ASCII inside the method itself.
 
     * For the LatestEntries example above, we could have very simple feed templates: