From 433659139596a75eab03940ea2029970de6ee287 Mon Sep 17 00:00:00 2001 From: Joseph Kocherhans Date: Tue, 15 May 2007 03:37:41 +0000 Subject: newforms-admin: Merged to [5243]. There are 3 failing tests in regressiontests.serializers_regress.tests.SerializerTests, but they fail in trunk also. git-svn-id: http://code.djangoproject.com/svn/django/branches/newforms-admin@5244 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/databrowse.txt | 6 +- docs/i18n.txt | 2 +- docs/newforms.txt | 609 ++++++++++++++++++++++++++++++++++++++++++++++++---- docs/testing.txt | 21 +- 4 files changed, 589 insertions(+), 49 deletions(-) (limited to 'docs') diff --git a/docs/databrowse.txt b/docs/databrowse.txt index e9691cc879..9c03e7e4ea 100644 --- a/docs/databrowse.txt +++ b/docs/databrowse.txt @@ -44,7 +44,11 @@ How to use Databrowse It doesn't matter where you put this, as long as it gets executed at some point. A good place for it is in your URLconf file (``urls.py``). - 3. Add the following line to your URLconf:: + 3. Change your URLconf to import the ``databrowse`` module:: + + from django.contrib import databrowse + + ...and add the following line to your URLconf:: (r'^databrowse/(.*)', databrowse.site.root), diff --git a/docs/i18n.txt b/docs/i18n.txt index 1d7a0063b2..27abadacc9 100644 --- a/docs/i18n.txt +++ b/docs/i18n.txt @@ -236,7 +236,7 @@ To pluralize, specify both the singular and plural forms with the ``{% plural %}`` tag, which appears within ``{% blocktrans %}`` and ``{% endblocktrans %}``. Example:: - {% blocktrans count list|count as counter %} + {% blocktrans count list|length as counter %} There is only one {{ name }} object. {% plural %} There are {{ counter }} {{ name }} objects. diff --git a/docs/newforms.txt b/docs/newforms.txt index ddb850f54c..ed43670960 100644 --- a/docs/newforms.txt +++ b/docs/newforms.txt @@ -9,28 +9,30 @@ framework. This document explains how to use this new library. Migration plan ============== -``django.newforms`` currently is only available in Django beginning -with the 0.96 release. the Django development version -- i.e., it's -not available in the Django 0.95 release. For the next Django release, -our plan is to do the following: +``django.newforms`` is new in Django's 0.96 release, but, as it won't be new +forever, we plan to rename it to ``django.forms`` in the future. The current +``django.forms`` package will be available as ``django.oldforms`` until Django +1.0, when we plan to remove it for good. - * As of revision [4208], we've copied the current ``django.forms`` to - ``django.oldforms``. This allows you to upgrade your code *now* rather - than waiting for the backwards-incompatible change and rushing to fix - your code after the fact. Just change your import statements like this:: +That has direct repercussions on the forward compatibility of your code. Please +read the following migration plan and code accordingly: + + * The old forms framework (the current ``django.forms``) has been copied to + ``django.oldforms``. Thus, you can start upgrading your code *now*, + rather than waiting for the future backwards-incompatible change, by + changing your import statements like this:: from django import forms # old from django import oldforms as forms # new - * At an undecided future date, we will move the current ``django.newforms`` - to ``django.forms``. This will be a backwards-incompatible change, and - anybody who is still using the old version of ``django.forms`` at that - time will need to change their import statements, as described in the - previous bullet. + * In the next Django release (0.97), we will move the current + ``django.newforms`` to ``django.forms``. This will be a + backwards-incompatible change, and anybody who is still using the old + version of ``django.forms`` at that time will need to change their import + statements, as described in the previous bullet. * We will remove ``django.oldforms`` in the release *after* the next Django - release -- the release that comes after the release in which we're - creating the new ``django.forms``. + release -- either 0.98 or 1.0, whichever comes first. With this in mind, we recommend you use the following import statement when using ``django.newforms``:: @@ -184,7 +186,7 @@ e-mail address:: >>> f.is_valid() False -Access the ``Form`` attribute ``errors`` to get a dictionary of error messages:: +Access the ``errors`` attribute to get a dictionary of error messages:: >>> f.errors {'sender': [u'Enter a valid e-mail address.'], 'subject': [u'This field is required.']} @@ -197,6 +199,10 @@ You can access ``errors`` without having to call ``is_valid()`` first. The form's data will be validated the first time either you call ``is_valid()`` or access ``errors``. +The validation routines will only get called once, regardless of how many times +you access ``errors`` or call ``is_valid()``. This means that if validation has +side effects, those side effects will only be triggered once. + Behavior of unbound forms ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -224,7 +230,7 @@ object. Regardless of whether you pass it a string in the format it's valid. Once you've created a ``Form`` instance with a set of data and validated it, -you can access the clean data via the ``clean_data`` attribute of the ``Form`` +you can access the clean data via the ``cleaned_data`` attribute of the ``Form`` object:: >>> data = {'subject': 'hello', @@ -234,7 +240,7 @@ object:: >>> f = ContactForm(data) >>> f.is_valid() True - >>> f.clean_data + >>> f.cleaned_data {'cc_myself': True, 'message': u'Hi there', 'sender': u'foo@example.com', 'subject': u'hello'} Note that any text-based field -- such as ``CharField`` or ``EmailField`` -- @@ -242,7 +248,7 @@ always cleans the input into a Unicode string. We'll cover the encoding implications later in this document. If your data does *not* validate, your ``Form`` instance will not have a -``clean_data`` attribute:: +``cleaned_data`` attribute:: >>> data = {'subject': '', ... 'message': 'Hi there', @@ -251,15 +257,15 @@ If your data does *not* validate, your ``Form`` instance will not have a >>> f = ContactForm(data) >>> f.is_valid() False - >>> f.clean_data + >>> f.cleaned_data Traceback (most recent call last): ... - AttributeError: 'ContactForm' object has no attribute 'clean_data' + AttributeError: 'ContactForm' object has no attribute 'cleaned_data' -``clean_data`` will always *only* contain a key for fields defined in the +``cleaned_data`` will always *only* contain a key for fields defined in the ``Form``, even if you pass extra data when you define the ``Form``. In this example, we pass a bunch of extra fields to the ``ContactForm`` constructor, -but ``clean_data`` contains only the form's fields:: +but ``cleaned_data`` contains only the form's fields:: >>> data = {'subject': 'hello', ... 'message': 'Hi there', @@ -271,9 +277,30 @@ but ``clean_data`` contains only the form's fields:: >>> f = ContactForm(data) >>> f.is_valid() True - >>> f.clean_data # Doesn't contain extra_field_1, etc. + >>> f.cleaned_data # Doesn't contain extra_field_1, etc. {'cc_myself': True, 'message': u'Hi there', 'sender': u'foo@example.com', 'subject': u'hello'} +``cleaned_data`` will include a key and value for *all* fields defined in the +``Form``, even if the data didn't include a value for fields that are not +required. In this example, the data dictionary doesn't include a value for the +``nick_name`` field, but ``cleaned_data`` includes it, with an empty value:: + + >>> class OptionalPersonForm(Form): + ... first_name = CharField() + ... last_name = CharField() + ... nick_name = CharField(required=False) + >>> data = {'first_name': u'John', 'last_name': u'Lennon'} + >>> f = OptionalPersonForm(data) + >>> f.is_valid() + True + >>> f.cleaned_data + {'nick_name': u'', 'first_name': u'John', 'last_name': u'Lennon'} + +In this above example, the ``cleaned_data`` value for ``nick_name`` is set to an +empty string, because ``nick_name`` is ``CharField``, and ``CharField``\s treat +empty values as an empty string. Each field type knows what its "blank" value +is -- e.g., for ``DateField``, it's ``None`` instead of the empty string. + Behavior of unbound forms ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -281,10 +308,10 @@ It's meaningless to request "clean" data in a form with no data, but, for the record, here's what happens with unbound forms:: >>> f = ContactForm() - >>> f.clean_data + >>> f.cleaned_data Traceback (most recent call last): ... - AttributeError: 'ContactForm' object has no attribute 'clean_data' + AttributeError: 'ContactForm' object has no attribute 'cleaned_data' Outputting forms as HTML ------------------------ @@ -454,7 +481,7 @@ field:: If ``auto_id`` is set to a string containing the format character ``'%s'``, then the form output will include ``