Django

Code

Show
Ignore:
Timestamp:
07/21/08 11:38:54 (6 months ago)
Author:
gwilson
Message:

Refs #7864 -- Updates to documentation for the oldforms/newforms switch.

  • Moved forms.txt to oldforms.txt
  • Moved newforms.txt to forms.txt
  • Updated links and most references to "newforms" (there are a few sections that need a more significant rewrite).
Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • django/trunk/docs/forms.txt

    r7978 r8020  
    1 ==================== 
    2 The newforms library 
    3 ==================== 
    4  
    5 ``django.newforms`` is Django's fantastic new form-handling library. It's a 
    6 replacement for ``django.forms``, the old form/manipulator/validation 
    7 framework. This document explains how to use this new library. 
     1================= 
     2The forms library 
     3================= 
     4 
     5``django.forms`` is Django's fantastic new form-handling library. It's a 
     6replacement for the old form/manipulator/validation framework, which has been 
     7moved to ``django.oldforms``. This document explains how to use this new 
     8library. 
    89 
    910Migration plan 
    …… 
    5556======== 
    5657 
    57 As with the ``django.forms`` ("manipulators") system before it, 
    58 ``django.newforms`` is intended to handle HTML form display, data processing 
     58As with the ``django.oldforms`` ("manipulators") system before it, 
     59``django.forms`` is intended to handle HTML form display, data processing 
    5960(validation) and redisplay. It's what you use if you want to perform 
    6061server-side validation for an HTML form. 
    …… 
    8990============ 
    9091 
    91 The primary way of using the ``newforms`` library is to create a form object. 
    92 Do this by subclassing ``django.newforms.Form`` and specifying the form's 
     92The primary way of using the ``forms`` library is to create a form object. 
     93Do this by subclassing ``django.forms.Form`` and specifying the form's 
    9394fields, in a declarative style that you'll be familiar with if you've used 
    9495Django database models. In this section, we'll iteratively develop a form 
    …… 
    9899Start with this basic ``Form`` subclass, which we'll call ``ContactForm``:: 
    99100 
    100     from django import newforms as forms 
     101    from django import forms 
    101102 
    102103    class ContactForm(forms.Form): 
    …… 
    585586~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
    586587 
    587 By default, forms use ``django.newforms.util.ErrorList`` to format validation 
     588By default, forms use ``django.forms.util.ErrorList`` to format validation 
    588589errors. If you'd like to use an alternate class for displaying errors, you can 
    589590pass that in at construction time:: 
    590591 
    591     >>> from django.newforms.util import ErrorList 
     592    >>> from django.forms.util import ErrorList 
    592593    >>> class DivErrorList(ErrorList): 
    593594    ...     def __unicode__(self): 
    …… 
    784785 
    785786Note that we check ``field.field.required`` and not ``field.required``. In the 
    786 template, ``field`` is a ``newforms.forms.BoundField`` instance, which holds 
     787template, ``field`` is a ``forms.forms.BoundField`` instance, which holds 
    787788the actual ``Field`` instance in its ``field`` attribute. 
    788789 
    …… 
    919920you can also instantiate them and use them directly to get a better idea of 
    920921how they work. Each ``Field`` instance has a ``clean()`` method, which takes 
    921 a single argument and either raises a ``django.newforms.ValidationError`` 
     922a single argument and either raises a ``django.forms.ValidationError`` 
    922923exception or returns the clean value:: 
    923924 
    …… 
    934935If you've used Django's old forms/validation framework, take care in noticing 
    935936this ``ValidationError`` is different than the previous ``ValidationError``. 
    936 This one lives at ``django.newforms.ValidationError`` rather than 
     937This one lives at ``django.forms.ValidationError`` rather than 
    937938``django.core.validators.ValidationError``. 
    938939 
    …… 
    11861187-------------------------- 
    11871188 
    1188 Naturally, the ``newforms`` library comes with a set of ``Field`` classes that 
     1189Naturally, the ``forms`` library comes with a set of ``Field`` classes that 
    11891190represent common validation needs. This section documents each built-in field. 
    11901191 
    …… 
    15891590If the built-in ``Field`` classes don't meet your needs, you can easily create 
    15901591custom ``Field`` classes. To do this, just create a subclass of 
    1591 ``django.newforms.Field``. Its only requirements are that it implement a 
     1592``django.forms.Field``. Its only requirements are that it implement a 
    15921593``clean()`` method and that its ``__init__()`` method accept the core arguments 
    15931594mentioned above (``required``, ``label``, ``initial``, ``widget``, 
    …… 
    16801681``is_valid_email()``. The full class:: 
    16811682 
    1682     from django import newforms as forms 
     1683    from django import forms 
    16831684 
    16841685    class MultiEmailField(forms.Field): 
    …… 
    25162517That's all the documentation for now. For more, see the file 
    25172518http://code.djangoproject.com/browser/django/trunk/tests/regressiontests/forms 
    2518 -- the unit tests for ``django.newforms``. This can give you a good idea of 
     2519-- the unit tests for ``django.forms``. This can give you a good idea of 
    25192520what's possible. (Each submodule there contains separate tests.) 
    25202521