==================== The newforms library ==================== ``django.newforms`` is Django's fantastic new form-handling library. It's a replacement for ``django.forms``, the old form/manipulator/validation framework. This document explains how to use this new library. Migration plan ============== ``django.newforms`` currently is only available in 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: * 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:: 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. * 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``. 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.forms`` ("manipulators") system before it, ``django.newforms`` is intended to handle HTML form display, 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 ``