Browse files

Added preliminary stub for docs/newforms.txt

git-svn-id: bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
1 parent e5de999 commit 625ae4ef9353977cf2d738893e8f98f2a78be2bc @adrianholovaty adrianholovaty committed Dec 6, 2006
Showing with 70 additions and 0 deletions.
  1. +70 −0 docs/newforms.txt
@@ -0,0 +1,70 @@
+The newforms library
+``django.newforms`` is a new replacement for ``django.forms``, the old Django
+form/manipulator/validation framework. This functionality is new in the Django
+development version -- i.e., it's not available in the Django 0.95 release.
+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 -- i.e., 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.
+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>``.
+ * **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
+-- the unit tests for ``django.newforms``. This can give you a good idea of
+what's possible.

0 comments on commit 625ae4e

Please sign in to comment.