72 lines
2.5 KiB
Plaintext
72 lines
2.5 KiB
Plaintext
====================
|
|
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.
|