Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Added preliminary stub for docs/newforms.txt

git-svn-id: http://code.djangoproject.com/svn/django/trunk@4168 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 625ae4ef9353977cf2d738893e8f98f2a78be2bc 1 parent e5de999
Adrian Holovaty authored December 06, 2006

Showing 1 changed file with 70 additions and 0 deletions. Show diff stats Hide diff stats

  1. 70  docs/newforms.txt
70  docs/newforms.txt
... ...
@@ -0,0 +1,70 @@
  1
+====================
  2
+The newforms library
  3
+====================
  4
+
  5
+``django.newforms`` is a new replacement for ``django.forms``, the old Django
  6
+form/manipulator/validation framework. This functionality is new in the Django
  7
+development version -- i.e., it's not available in the Django 0.95 release.
  8
+
  9
+This document explains how to use this new form library.
  10
+
  11
+Migration plan
  12
+==============
  13
+
  14
+``django.newforms`` currently is only available in the Django development version
  15
+-- i.e., it's not available in the Django 0.95 release. For the next Django
  16
+release, our plan is to do the following:
  17
+
  18
+    * Move the current ``django.forms`` to ``django.oldforms``. This will allow
  19
+      for an eased migration of form code. You'll just have to change your
  20
+      import statements::
  21
+
  22
+          from django import forms             # old
  23
+          from django import oldforms as forms # new
  24
+
  25
+    * Move the current ``django.newforms`` to ``django.forms``.
  26
+
  27
+    * We will remove ``django.oldforms`` in the release *after* the next Django
  28
+      release -- i.e., the release that comes after the release in which we're
  29
+      creating ``django.oldforms``.
  30
+
  31
+With this in mind, we recommend you use the following import statement when
  32
+using ``django.newforms``::
  33
+
  34
+    from django import newforms as forms
  35
+
  36
+This way, your code can refer to the ``forms`` module, and when
  37
+``django.newforms`` is renamed to ``django.forms``, you'll only have to change
  38
+your ``import`` statements.
  39
+
  40
+If you prefer "``import *``" syntax, you can do the following::
  41
+
  42
+    from django.newforms import *
  43
+
  44
+This will import all fields, widgets, form classes and other various utilities
  45
+into your local namespace. Some people find this convenient; others find it
  46
+too messy. The choice is yours.
  47
+
  48
+Overview
  49
+========
  50
+
  51
+As the ``django.forms`` system before it, ``django.newforms`` is intended to
  52
+handle HTML form display, validation and redisplay. It's what you use if you
  53
+want to perform server-side validation for an HTML form.
  54
+
  55
+The library deals with these concepts:
  56
+
  57
+    * **Widget** -- A class that corresponds to an HTML form widget, e.g.
  58
+      ``<input type="text">`` or ``<textarea>``.
  59
+    * **Field** -- A class that is responsible for doing validation, e.g.
  60
+      an ``EmailField`` that makes sure its data is a valid e-mail address.
  61
+    * **Form** -- A collection of fields that knows how to validate itself and
  62
+      display itself as HTML.
  63
+
  64
+More coming soon
  65
+================
  66
+
  67
+That's all the documentation for now. For more, see the file
  68
+http://code.djangoproject.com/browser/django/trunk/tests/regressiontests/forms/tests.py
  69
+-- the unit tests for ``django.newforms``. This can give you a good idea of
  70
+what's possible.

0 notes on commit 625ae4e

Please sign in to comment.
Something went wrong with that request. Please try again.