django/docs/newforms.txt

====================
The newforms library
====================

``django.newforms`` is a new replacement for ``django.forms``, the old Django
form/manipulator/validation framework. This document explains how to use this
new form 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:

    * Move the current ``django.forms`` to ``django.oldforms``. This will allow
      for an eased migration of form code. You'll just have to change your
      import statements::

          from django import forms             # old
          from django import oldforms as forms # new

    * Move the current ``django.newforms`` to ``django.forms``.

    * 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 ``django.oldforms``.

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 the ``django.forms`` 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.

The library deals with these concepts:

    * **Widget** -- A class that corresponds to an HTML form widget, e.g.
      ``<input type="text">`` or ``<textarea>``. This handles rendering of the
      widget as HTML.

    * **Field** -- A class that is responsible for doing validation, e.g.
      an ``EmailField`` that makes sure its data is a valid e-mail address.

    * **Form** -- A collection of fields that knows how to validate itself and
      display itself as HTML.

More coming soon
================

That's all the documentation for now. For more, see the file
http://code.djangoproject.com/browser/django/trunk/tests/regressiontests/forms/tests.py
-- the unit tests for ``django.newforms``. This can give you a good idea of
what's possible.