Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Made some changes to docs/newforms.txt that I'd had lying around

git-svn-id: http://code.djangoproject.com/svn/django/trunk@5442 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 83fe33e2774b9ae59007f39ef61abce73e09c54f 1 parent 8494ffc
Adrian Holovaty authored June 07, 2007

Showing 1 changed file with 51 additions and 11 deletions. Show diff stats Hide diff stats

  1. 62  docs/newforms.txt
62  docs/newforms.txt
@@ -299,12 +299,14 @@ required. In this example, the data dictionary doesn't include a value for the
299 299
 In this above example, the ``cleaned_data`` value for ``nick_name`` is set to an
300 300
 empty string, because ``nick_name`` is ``CharField``, and ``CharField``\s treat
301 301
 empty values as an empty string. Each field type knows what its "blank" value
302  
-is -- e.g., for ``DateField``, it's ``None`` instead of the empty string.
  302
+is -- e.g., for ``DateField``, it's ``None`` instead of the empty string. For
  303
+full details on each field's behavior in this case, see the "Empty value" note
  304
+for each field in the "Built-in ``Field`` classes" section below.
303 305
 
304 306
 Behavior of unbound forms
305 307
 ~~~~~~~~~~~~~~~~~~~~~~~~~
306 308
 
307  
-It's meaningless to request "clean" data in a form with no data, but, for the
  309
+It's meaningless to request "cleaned" data in a form with no data, but, for the
308 310
 record, here's what happens with unbound forms::
309 311
 
310 312
     >>> f = ContactForm()
@@ -606,8 +608,13 @@ Using forms in views and templates
606 608
 ----------------------------------
607 609
 
608 610
 Let's put this all together and use the ``ContactForm`` example in a Django
609  
-view and template. This example view displays the contact form by default and
610  
-validates/processes it if accessed via a POST request::
  611
+view and template.
  612
+
  613
+Simple view example
  614
+~~~~~~~~~~~~~~~~~~~
  615
+
  616
+This example view displays the contact form by default and validates/processes
  617
+it if accessed via a POST request::
611 618
 
612 619
     def contact(request):
613 620
         if request.method == 'POST':
@@ -619,12 +626,12 @@ validates/processes it if accessed via a POST request::
619 626
             form = ContactForm()
620 627
         return render_to_response('contact.html', {'form': form})
621 628
 
622  
-Simple template output
623  
-~~~~~~~~~~~~~~~~~~~~~~
  629
+Simple template example
  630
+~~~~~~~~~~~~~~~~~~~~~~~
624 631
 
625  
-The template, ``contact.html``, is responsible for displaying the form as HTML.
626  
-To do this, we can use the techniques outlined in the "Outputting forms as HTML"
627  
-section above.
  632
+The template in the above view example, ``contact.html``, is responsible for
  633
+displaying the form as HTML. To do this, we can use the techniques outlined in
  634
+the "Outputting forms as HTML" section above.
628 635
 
629 636
 The simplest way to display a form's HTML is to use the variable on its own,
630 637
 like this::
@@ -677,7 +684,7 @@ The easiest way is to iterate over the form's fields, with
677 684
 
678 685
 This iteration technique is useful if you want to apply the same HTML
679 686
 formatting to each field, or if you don't know the names of the form fields
680  
-ahead of time. Note that the fields will be listed in the order in which
  687
+ahead of time. Note that the fields will be iterated over in the order in which
681 688
 they're defined in the ``Form`` class.
682 689
 
683 690
 Alternatively, you can arrange the form's fields explicitly, by name. Do that
@@ -701,7 +708,10 @@ For example::
701 708
 Subclassing forms
702 709
 -----------------
703 710
 
704  
-If you subclass a custom ``Form`` class, the resulting ``Form`` class will
  711
+If you have multiple ``Form`` classes that share fields, you can use
  712
+subclassing to remove redundancy.
  713
+
  714
+When you subclass a custom ``Form`` class, the resulting subclass will
705 715
 include all fields of the parent class(es), followed by the fields you define
706 716
 in the subclass.
707 717
 
@@ -1202,6 +1212,36 @@ custom ``Field`` classes. To do this, just create a subclass of
1202 1212
 mentioned above (``required``, ``label``, ``initial``, ``widget``,
1203 1213
 ``help_text``).
1204 1214
 
  1215
+A simple example
  1216
+~~~~~~~~~~~~~~~~
  1217
+
  1218
+Here's a simple example of a custom field that validates its input is a string
  1219
+containing comma-separated e-mail addresses, with at least one address. We'll
  1220
+keep it simple and assume e-mail validation is contained in a function called
  1221
+``is_valid_email()``. The full class::
  1222
+
  1223
+    from django import newforms as forms
  1224
+
  1225
+    class MultiEmailField(forms.Field):
  1226
+        def clean(self, value):
  1227
+            emails = value.split(',')
  1228
+            for email in emails:
  1229
+                if not is_valid_email(email):
  1230
+                    raise forms.ValidationError('%s is not a valid e-mail address.' % email)
  1231
+            if not emails:
  1232
+                raise forms.ValidationError('Enter at least one e-mail address.')
  1233
+            return emails
  1234
+
  1235
+Let's alter the ongoing ``ContactForm`` example to demonstrate how you'd use
  1236
+this in a form. Simply use ``MultiEmailField`` instead of ``forms.EmailField``,
  1237
+like so::
  1238
+
  1239
+    class ContactForm(forms.Form):
  1240
+        subject = forms.CharField(max_length=100)
  1241
+        message = forms.CharField()
  1242
+        senders = MultiEmailField()
  1243
+        cc_myself = forms.BooleanField()
  1244
+
1205 1245
 Generating forms for models
1206 1246
 ===========================
1207 1247
 

0 notes on commit 83fe33e

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