diff --git a/docs/add_ons.txt b/docs/add_ons.txt index 029e314f120..3f226386fd3 100644 --- a/docs/add_ons.txt +++ b/docs/add_ons.txt @@ -76,7 +76,7 @@ Requires the sites_ contrib package to be installed as well. formtools ========= -A set of high-level abstractions for Django forms (django.newforms). +A set of high-level abstractions for Django forms (django.forms). django.contrib.formtools.preview -------------------------------- diff --git a/docs/api_stability.txt b/docs/api_stability.txt index 769359b75e8..2a10f34a41a 100644 --- a/docs/api_stability.txt +++ b/docs/api_stability.txt @@ -115,6 +115,6 @@ change: .. _template language: ../templates/ .. _transactions: ../transactions/ .. _url dispatch: ../url_dispatch/ -.. _forms and validation: ../forms/ +.. _forms and validation: ../oldforms/ .. _serialization: ../serialization/ .. _authentication: ../authentication/ diff --git a/docs/authentication.txt b/docs/authentication.txt index cd76731bc47..5e6b4b1a8b3 100644 --- a/docs/authentication.txt +++ b/docs/authentication.txt @@ -517,7 +517,7 @@ It's your responsibility to provide the login form in a template called template context variables: * ``form``: A ``Form`` object representing the login form. See the - `newforms documentation`_ for more on ``Form`` objects. + `forms documentation`_ for more on ``FormWrapper`` objects. * ``next``: The URL to redirect to after successful login. This may contain a query string, too. * ``site_name``: The name of the current ``Site``, according to the @@ -557,7 +557,7 @@ block:: {% endblock %} -.. _newforms documentation: ../newforms/ +.. _forms documentation: ../forms/ .. _site framework docs: ../sites/ Other built-in views diff --git a/docs/custom_model_fields.txt b/docs/custom_model_fields.txt index cbaac873e36..86d2986ffc5 100644 --- a/docs/custom_model_fields.txt +++ b/docs/custom_model_fields.txt @@ -111,7 +111,7 @@ into the precise details of what ``Field`` can do later on; for now, suffice it to say that everything descends from ``Field`` and then customizes key pieces of the class behavior. -.. _form fields: ../newforms/#fields +.. _form fields: ../forms/#fields It's important to realize that a Django field class is not what is stored in your model attributes. The model attributes contain normal Python objects. The @@ -493,8 +493,8 @@ This assumes we're imported a ``MyFormField`` field class (which has its own default widget). This document doesn't cover the details of writing custom form fields. -.. _helper functions: ../newforms/#generating-forms-for-models -.. _forms documentation: ../newforms/ +.. _helper functions: ../forms/#generating-forms-for-models +.. _forms documentation: ../forms/ ``get_internal_type(self)`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/form_for_model.txt b/docs/form_for_model.txt index ddca9aae186..a394cd2c547 100644 --- a/docs/form_for_model.txt +++ b/docs/form_for_model.txt @@ -20,13 +20,13 @@ For this reason, Django provides a few helper functions that let you create a ``form_for_model()`` -------------------- -The method ``django.newforms.form_for_model()`` creates a form based on the +The method ``django.forms.form_for_model()`` creates a form based on the definition of a specific model. Pass it the model class, and it will return a ``Form`` class that contains a form field for each model field. For example:: - >>> from django.newforms import form_for_model + >>> from django.forms import form_for_model # Create the form class. >>> ArticleForm = form_for_model(Article) @@ -93,11 +93,11 @@ the full list of conversions: As you might expect, the ``ForeignKey`` and ``ManyToManyField`` model field types are special cases: - * ``ForeignKey`` is represented by ``django.newforms.ModelChoiceField``, + * ``ForeignKey`` is represented by ``django.forms.ModelChoiceField``, which is a ``ChoiceField`` whose choices are a model ``QuerySet``. * ``ManyToManyField`` is represented by - ``django.newforms.ModelMultipleChoiceField``, which is a + ``django.forms.ModelMultipleChoiceField``, which is a ``MultipleChoiceField`` whose choices are a model ``QuerySet``. In addition, each generated form field has attributes set as follows: @@ -228,7 +228,7 @@ Using an alternate base class ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you want to add custom methods to the form generated by -``form_for_model()``, write a class that extends ``django.newforms.BaseForm`` +``form_for_model()``, write a class that extends ``django.forms.BaseForm`` and contains your custom methods. Then, use the ``form`` argument to ``form_for_model()`` to tell it to use your custom form as its base class. For example:: @@ -412,8 +412,8 @@ note is that the form display in the ``GET`` branch of the function will use the values from the ``message`` instance as initial values for the form field. -.. _contact form: ../newforms/#simple-view-example -.. _`simple example view`: ../newforms/#simple-view-example +.. _contact form: ../forms/#simple-view-example +.. _`simple example view`: ../forms/#simple-view-example When should you use ``form_for_model()`` and ``form_for_instance()``? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/form_preview.txt b/docs/form_preview.txt index e03de361874..171174704cd 100644 --- a/docs/form_preview.txt +++ b/docs/form_preview.txt @@ -13,7 +13,7 @@ Python class. Overview ========= -Given a ``django.newforms.Form`` subclass that you define, this application +Given a ``django.forms.Form`` subclass that you define, this application takes care of the following workflow: 1. Displays the form as HTML on a Web page. @@ -65,7 +65,7 @@ How to use ``FormPreview`` from myapp.preview import SomeModelFormPreview from myapp.models import SomeModel - from django import newforms as forms + from django import forms ...and add the following line to the appropriate model in your URLconf:: diff --git a/docs/form_wizard.txt b/docs/form_wizard.txt index cd9e58ded1a..661127e5b04 100644 --- a/docs/form_wizard.txt +++ b/docs/form_wizard.txt @@ -17,7 +17,7 @@ etc. The term "wizard," in this context, is `explained on Wikipedia`_. .. _explained on Wikipedia: http://en.wikipedia.org/wiki/Wizard_%28software%29 -.. _forms: ../newforms/ +.. _forms: ../forms/ How it works ============ @@ -41,7 +41,7 @@ Usage This application handles as much machinery for you as possible. Generally, you just have to do these things: - 1. Define a number of ``django.newforms`` ``Form`` classes -- one per wizard + 1. Define a number of ``django.forms`` ``Form`` classes -- one per wizard page. 2. Create a ``FormWizard`` class that specifies what to do once all of your forms have been submitted and validated. This also lets you override some @@ -55,8 +55,8 @@ Defining ``Form`` classes ========================= The first step in creating a form wizard is to create the ``Form`` classes. -These should be standard ``django.newforms`` ``Form`` classes, covered in the -`newforms documentation`_. +These should be standard ``django.forms`` ``Form`` classes, covered in the +`forms documentation`_. These classes can live anywhere in your codebase, but convention is to put them in a file called ``forms.py`` in your application. @@ -65,7 +65,7 @@ For example, let's write a "contact form" wizard, where the first page's form collects the sender's e-mail address and subject, and the second page collects the message itself. Here's what the ``forms.py`` might look like:: - from django import newforms as forms + from django import forms class ContactForm1(forms.Form): subject = forms.CharField(max_length=100) @@ -78,7 +78,7 @@ the message itself. Here's what the ``forms.py`` might look like:: data between pages, you may not include a ``FileField`` in any form except the last one. -.. _newforms documentation: ../newforms/ +.. _forms documentation: ../forms/ Creating a ``FormWizard`` class =============================== @@ -94,7 +94,7 @@ which specifies what should happen when the data for *every* form is submitted and validated. This method is passed two arguments: * ``request`` -- an HttpRequest_ object - * ``form_list`` -- a list of ``django.newforms`` ``Form`` classes + * ``form_list`` -- a list of ``django.forms`` ``Form`` classes In this simplistic example, rather than perform any database operation, the method simply renders a template of the validated data:: @@ -209,7 +209,7 @@ Default implementation:: def prefix_for_step(self, step): return str(step) -.. _form prefix documentation: ../newforms/#prefixes-for-forms +.. _form prefix documentation: ../forms/#prefixes-for-forms ``render_hash_failure`` ~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/forms.txt b/docs/forms.txt index 18d322a8eb8..7781191e357 100644 --- a/docs/forms.txt +++ b/docs/forms.txt @@ -1,700 +1,2523 @@ -=============================== -Forms, fields, and manipulators -=============================== +================= +The forms library +================= -Forwards-compatibility note -=========================== +``django.forms`` is Django's fantastic new form-handling library. It's a +replacement for the old form/manipulator/validation framework, which has been +moved to ``django.oldforms``. This document explains how to use this new +library. -The legacy forms/manipulators system described in this document is going to be -replaced in the next Django release. If you're starting from scratch, we -strongly encourage you not to waste your time learning this. Instead, learn and -use the django.newforms system, which we have begun to document in the -`newforms documentation`_. +Migration plan +============== -If you have legacy form/manipulator code, read the "Migration plan" section in -that document to understand how we're making the switch. +``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. -.. _newforms documentation: ../newforms/ +That has direct repercussions on the forward compatibility of your code. Please +read the following migration plan and code accordingly: -Introduction + * 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 + + * 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 -- 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``:: + + from django import newforms as forms + +This way, your code can refer to the ``forms`` module, and when +``django.newforms`` is renamed to ``django.forms``, you'll only have to change +your ``import`` statements. + +If you prefer "``import *``" syntax, you can do the following:: + + from django.newforms import * + +This will import all fields, widgets, form classes and other various utilities +into your local namespace. Some people find this convenient; others find it +too messy. The choice is yours. + +Overview +======== + +As with the ``django.oldforms`` ("manipulators") system before it, +``django.forms`` is intended to handle HTML form display, data processing +(validation) and redisplay. It's what you use if you want to perform +server-side validation for an HTML form. + +For example, if your Web site has a contact form that visitors can use to +send you e-mail, you'd use this library to implement the display of the HTML +form fields, along with the form validation. Any time you need to use an HTML +``