From 5467c34b0bad006ae49265d2ca417e9807ec2a8d Mon Sep 17 00:00:00 2001 From: Adrian Holovaty Date: Mon, 11 Dec 2006 03:03:54 +0000 Subject: [PATCH] Added more to docs/newforms.txt git-svn-id: http://code.djangoproject.com/svn/django/trunk@4193 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/newforms.txt | 221 ++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 214 insertions(+), 7 deletions(-) diff --git a/docs/newforms.txt b/docs/newforms.txt index 9bfbc75ee78..ee545661840 100644 --- a/docs/newforms.txt +++ b/docs/newforms.txt @@ -46,9 +46,14 @@ 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. +As the ``django.forms`` ("manipulators") 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. + +For example, if your Web site has a contact form that visitors can use to +send you e-mail, you'd use this library to implement the display of the HTML +form fields, along with the form validation. Any time you need to use an HTML +``
``, you can use this library. The library deals with these concepts: @@ -62,13 +67,206 @@ The library deals with these concepts: * **Form** -- A collection of fields that knows how to validate itself and display itself as HTML. +Form objects +============ +The primary way of using the ``newforms`` library is to create a form object. +Do this by subclassing ``django.newforms.Form`` and specifying the form's +fields, in a declarative style that you'll be familiar with if you've used +Django database models. In this section, we'll iteratively develop a form +object that you might to implement "contact me" functionality on your personal +Web site. -Using forms with templates -========================== +Start with this basic ``Form`` subclass, which we'll call ``ContactForm``:: -Using forms in views -==================== + from django import newforms as forms + + class ContactForm(forms.Form): + subject = forms.CharField(max_length=100) + message = forms.CharField() + sender = forms.EmailField() + cc_myself = forms.BooleanField() + +A form is composed of ``Field`` objects. In this case, our form has four +fields: ``subject``, ``message``, ``sender`` and ``cc_myself``. We'll explain +the different types of fields -- e.g., ``CharField`` and ``EmailField`` -- +shortly. + +Outputting forms as HTML +------------------------ + +The first thing we can do with this is output it as HTML. To do so, instantiate +it and ``print`` it:: + + >>> f = ContactForm() + >>> print f + + + + + +This default output is a two-column HTML table, with a ```` for each field. +Notice the following: + + * For flexibility, the output does *not* include the ```` and + ``
`` tags, nor does it include the ```` and ``
`` + tags or an ```` tag. It's your job to do that. + + * Each field type has a default HTML representation. ``CharField`` and + ``EmailField`` are represented by an ````. + ``BooleanField`` is represented by an ````. Note + these are merely sensible defaults; you can specify which HTML to use for + a given field by using ``widgets``, which we'll explain shortly. + + * The HTML ``name`` for each tag is taken directly from its attribute name + in the ``ContactForm`` class. + + * The text label for each field -- e.g. ``'Subject:'``, ``'Message:'`` and + ``'CC myself:'`` is generated from the field name by converting all + underscores to spaces and upper-casing the first letter. Again, note + these are merely sensible defaults; you can also specify labels manually. + + * Each text label is surrounded in an HTML ``