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/add_ons.txt

    r7294 r8020  
    7777========= 
    7878 
    79 A set of high-level abstractions for Django forms (django.newforms). 
     79A set of high-level abstractions for Django forms (django.forms). 
    8080 
    8181django.contrib.formtools.preview 

  • django/trunk/docs/api_stability.txt

    r7294 r8020  
    116116.. _transactions: ../transactions/ 
    117117.. _url dispatch: ../url_dispatch/ 
    118 .. _forms and validation: ../forms/ 
     118.. _forms and validation: ../oldforms/ 
    119119.. _serialization: ../serialization/ 
    120120.. _authentication: ../authentication/ 

  • django/trunk/docs/authentication.txt

    r7967 r8020  
    518518 
    519519    * ``form``: A ``Form`` object representing the login form. See the 
    520       `newforms documentation`_ for more on ``Form`` objects. 
     520      `forms documentation`_ for more on ``FormWrapper`` objects. 
    521521    * ``next``: The URL to redirect to after successful login. This may contain 
    522522      a query string, too. 
    …… 
    558558    {% endblock %} 
    559559 
    560 .. _newforms documentation: ../newforms/ 
     560.. _forms documentation: ../forms/ 
    561561.. _site framework docs: ../sites/ 
    562562 

  • django/trunk/docs/custom_model_fields.txt

    r7967 r8020  
    112112of the class behavior. 
    113113 
    114 .. _form fields: ../newforms/#fields 
     114.. _form fields: ../forms/#fields 
    115115 
    116116It's important to realize that a Django field class is not what is stored in 
    …… 
    494494fields. 
    495495 
    496 .. _helper functions: ../newforms/#generating-forms-for-models 
    497 .. _forms documentation: ../newforms/ 
     496.. _helper functions: ../forms/#generating-forms-for-models 
     497.. _forms documentation: ../forms/ 
    498498 
    499499``get_internal_type(self)`` 

  • django/trunk/docs/form_for_model.txt

    r7294 r8020  
    2121-------------------- 
    2222 
    23 The method ``django.newforms.form_for_model()`` creates a form based on the 
     23The method ``django.forms.form_for_model()`` creates a form based on the 
    2424definition of a specific model. Pass it the model class, and it will return a 
    2525``Form`` class that contains a form field for each model field. 
    …… 
    2727For example:: 
    2828 
    29     >>> from django.newforms import form_for_model 
     29    >>> from django.forms import form_for_model 
    3030 
    3131    # Create the form class. 
    …… 
    9494types are special cases: 
    9595 
    96     * ``ForeignKey`` is represented by ``django.newforms.ModelChoiceField``, 
     96    * ``ForeignKey`` is represented by ``django.forms.ModelChoiceField``, 
    9797      which is a ``ChoiceField`` whose choices are a model ``QuerySet``. 
    9898 
    9999    * ``ManyToManyField`` is represented by 
    100       ``django.newforms.ModelMultipleChoiceField``, which is a 
     100      ``django.forms.ModelMultipleChoiceField``, which is a 
    101101      ``MultipleChoiceField`` whose choices are a model ``QuerySet``. 
    102102 
    …… 
    229229 
    230230If you want to add custom methods to the form generated by 
    231 ``form_for_model()``, write a class that extends ``django.newforms.BaseForm`` 
     231``form_for_model()``, write a class that extends ``django.forms.BaseForm`` 
    232232and contains your custom methods. Then, use the ``form`` argument to 
    233233``form_for_model()`` to tell it to use your custom form as its base class. 
    …… 
    413413form field. 
    414414 
    415 .. _contact form: ../newforms/#simple-view-example 
    416 .. _`simple example view`: ../newforms/#simple-view-example 
     415.. _contact form: ../forms/#simple-view-example 
     416.. _`simple example view`: ../forms/#simple-view-example 
    417417 
    418418When should you use ``form_for_model()`` and ``form_for_instance()``? 

  • django/trunk/docs/form_preview.txt

    r7675 r8020  
    1414========= 
    1515 
    16 Given a ``django.newforms.Form`` subclass that you define, this application 
     16Given a ``django.forms.Form`` subclass that you define, this application 
    1717takes care of the following workflow: 
    1818 
    …… 
    6666           from myapp.preview import SomeModelFormPreview 
    6767           from myapp.models import SomeModel 
    68            from django import newforms as forms 
     68           from django import forms 
    6969 
    7070       ...and add the following line to the appropriate model in your URLconf:: 

  • 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 

  • django/trunk/docs/form_wizard.txt

    r7294 r8020  
    1818 
    1919.. _explained on Wikipedia: http://en.wikipedia.org/wiki/Wizard_%28software%29 
    20 .. _forms: ../newforms/ 
     20.. _forms: ../forms/ 
    2121 
    2222How it works 
    …… 
    4242just have to do these things: 
    4343 
    44     1. Define a number of ``django.newforms`` ``Form`` classes -- one per wizard 
     44    1. Define a number of ``django.forms`` ``Form`` classes -- one per wizard 
    4545       page. 
    4646    2. Create a ``FormWizard`` class that specifies what to do once all of your 
    …… 
    5656 
    5757The first step in creating a form wizard is to create the ``Form`` classes. 
    58 These should be standard ``django.newforms`` ``Form`` classes, covered in the 
    59 `newforms documentation`_. 
     58These should be standard ``django.forms`` ``Form`` classes, covered in the 
     59`forms documentation`_. 
    6060 
    6161These classes can live anywhere in your codebase, but convention is to put them 
    …… 
    6666the message itself. Here's what the ``forms.py`` might look like:: 
    6767 
    68     from django import newforms as forms 
     68    from django import forms 
    6969 
    7070    class ContactForm1(forms.Form): 
    …… 
    7979last one. 
    8080 
    81 .. _newforms documentation: ../newforms/ 
     81.. _forms documentation: ../forms/ 
    8282 
    8383Creating a ``FormWizard`` class 
    …… 
    9595 
    9696    * ``request`` -- an HttpRequest_ object 
    97     * ``form_list`` -- a list of ``django.newforms`` ``Form`` classes 
     97    * ``form_list`` -- a list of ``django.forms`` ``Form`` classes 
    9898 
    9999In this simplistic example, rather than perform any database operation, the 
    …… 
    210210        return str(step) 
    211211 
    212 .. _form prefix documentation: ../newforms/#prefixes-for-forms 
     212.. _form prefix documentation: ../forms/#prefixes-for-forms 
    213213 
    214214``render_hash_failure`` 

  • django/trunk/docs/generic_views.txt

    r7952 r8020  
    985985          </form> 
    986986 
    987       See the `newforms documentation`_ for more information about using 
     987      See the `forms documentation`_ for more information about using 
    988988      ``Form`` objects in templates. 
    989989 
    990990.. _authentication system: ../authentication/ 
    991991.. _ModelForm docs: ../newforms/modelforms 
    992 .. _newforms documentation: ../newforms/ 
     992.. _forms documentation: ../forms/ 
    993993 
    994994``django.views.generic.create_update.update_object`` 

  • django/trunk/docs/index.txt

    r7374 r8020  
    3434   templates 
    3535   templates_python 
    36    newforms 
     36   forms 
    3737   modelforms 
    3838   testing 

  • django/trunk/docs/localflavor.txt

    r7989 r8020  
    1212 
    1313Most of the ``localflavor`` add-ons are localized form components deriving from 
    14 the newforms_ framework -- for example, a ``USStateField`` that knows how to 
     14the forms_ framework -- for example, a ``USStateField`` that knows how to 
    1515validate U.S. state abbreviations, and a ``FISocialSecurityNumber`` that knows 
    1616how to validate Finnish social security numbers. 
    …… 
    2020French telephone number:: 
    2121 
    22     from django import newforms as forms 
     22    from django import forms 
    2323    from django.contrib.localflavor import fr 
    2424 
    …… 
    5959useful code that is not specific to one particular country or culture. 
    6060Currently, it defines date and datetime input fields based on those from 
    61 newforms_, but with non-US default formats. Here's an example of how to use 
     61forms_, but with non-US default formats. Here's an example of how to use 
    6262them:: 
    6363 
    64     from django import newforms as forms 
     64    from django import forms 
    6565    from django.contrib.localflavor import generic 
    6666 
    …… 
    9393.. _United Kingdom: `United Kingdom (django.contrib.localflavor.uk)`_ 
    9494.. _United States of America: `United States of America (django.contrib.localflavor.us)`_ 
    95 .. _newforms: ../newforms/ 
     95.. _forms: ../forms/ 
    9696 
    9797Adding flavors 

  • django/trunk/docs/model-api.txt

    r7977 r8020  
    717717Django comes with quite a few validators. They're in ``django.core.validators``. 
    718718 
    719 .. _validator docs: ../forms/#validators 
     719.. _validator docs: ../oldforms/#validators 
    720720 
    721721Verbose field names 

  • django/trunk/docs/modelforms.txt

    r7967 r8020  
    1 ========================== 
    2 Using newforms with models 
    3 ========================== 
     1======================= 
     2Using forms with models 
     3======================= 
    44 
    55``ModelForm`` 
    …… 
    1717For example:: 
    1818 
    19     >>> from django.newforms import ModelForm 
     19    >>> from django.forms import ModelForm 
    2020 
    2121    # Create the form class. 
    …… 
    8787types are special cases: 
    8888 
    89     * ``ForeignKey`` is represented by ``django.newforms.ModelChoiceField``, 
     89    * ``ForeignKey`` is represented by ``django.forms.ModelChoiceField``, 
    9090      which is a ``ChoiceField`` whose choices are a model ``QuerySet``. 
    9191 
    9292    * ``ManyToManyField`` is represented by 
    93       ``django.newforms.ModelMultipleChoiceField``, which is a 
     93      ``django.forms.ModelMultipleChoiceField``, which is a 
    9494      ``MultipleChoiceField`` whose choices are a model ``QuerySet``. 
    9595 
    …… 
    122122 
    123123    from django.db import models 
    124     from django.newforms import ModelForm 
     124    from django.forms import ModelForm 
    125125 
    126126    TITLE_CHOICES = ( 
    …… 
    241241 
    242242Other than the ``save()`` and ``save_m2m()`` methods, a ``ModelForm`` 
    243 works exactly the same way as any other ``newforms`` form. For 
     243works exactly the same way as any other ``forms`` form. For 
    244244example, the ``is_valid()`` method is used to check for validity, the 
    245245``is_multipart()`` method is used to determine whether a form requires 
    246246multipart file upload (and hence whether ``request.FILES`` must be 
    247 passed to the form), etc. See `the standard newforms documentation`_ 
     247passed to the form), etc. See `the standard forms documentation`_ 
    248248for more information. 
    249249 
    250 .. _the standard newforms documentation: ../newforms/ 
     250.. _the standard forms documentation: ../forms/ 
    251251 
    252252Using a subset of fields on the form 

  • django/trunk/docs/oldforms.txt

    r7294 r8020  
    99replaced in the next Django release. If you're starting from scratch, we 
    1010strongly encourage you not to waste your time learning this. Instead, learn and 
    11 use the django.newforms system, which we have begun to document in the 
    12 `newforms documentation`_. 
     11use the django.forms system, which we have begun to document in the 
     12`forms documentation`_. 
    1313 
    1414If you have legacy form/manipulator code, read the "Migration plan" section in 
    1515that document to understand how we're making the switch. 
    1616 
    17 .. _newforms documentation: ../newforms/ 
     17.. _forms documentation: ../forms/ 
    1818 
    1919Introduction 
    …… 
    8080    from django.shortcuts import render_to_response 
    8181    from django.http import Http404, HttpResponse, HttpResponseRedirect 
    82     from django import forms 
     82    from django import oldforms as forms 
    8383    from mysite.myapp.models import Place 
    8484 
    …… 
    376376for a "contact" form on a website:: 
    377377 
    378     from django import forms 
     378    from django import oldforms as forms 
    379379 
    380380    urgency_choices = ( 
    …… 
    486486 
    487487    from django.core import validators 
    488     from django import forms 
     488    from django import oldforms as forms 
    489489 
    490490    class ContactManipulator(forms.Manipulator): 
    …… 
    589589 
    590590    from django.core import validators 
    591     from django import forms 
     591    from django import oldforms as forms 
    592592 
    593593    power_validator = validators.IsAPowerOf(2) 

  • django/trunk/docs/upload_handling.txt

    r7970 r8020  
    1818Consider a simple form containing a ``FileField``:: 
    1919 
    20     from django import newforms as forms 
     20    from django import forms 
    2121 
    2222    class UploadFileForm(forms.Form): 
    …… 
    4949        return render_to_response('upload.html', {'form': form}) 
    5050 
    51 .. _binding uploaded files to a form: ../newforms/#binding-uploaded-files-to-a- form 
     51.. _binding uploaded files to a form: ../forms/#binding-uploaded-files-to-a- form 
    5252 
    5353Notice that we have to pass ``request.FILES`` into the form's constructor; this