Source

django / docs / forms.txt

Full commit
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
=================
The forms library
=================

``django.forms`` is Django's form-handling library.

.. admonition:: Looking for oldforms?

    ``django.forms`` was once called ``newforms`` since it replaced Django's
    original form/manipulator/validation framework. The old form handling
    library is still available as `django.oldforms`_, but will be removed
    in a future version of Django.

.. _django.oldforms: ../oldforms/

Overview
========

``django.forms`` is intended to handle HTML form display, data processing
(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
``<form>``, you can use this library.

The library deals with these concepts:

    * **Widget** -- A class that corresponds to an HTML form widget, e.g.
      ``<input type="text">`` or ``<textarea>``. This handles rendering of the
      widget as HTML.

    * **Field** -- A class that is responsible for doing validation, e.g.
      an ``EmailField`` that makes sure its data is a valid e-mail address.

    * **Form** -- A collection of fields that knows how to validate itself and
      display itself as HTML.

    * **Media** -- A definition of the CSS and JavaScript resources that are
      required to render a form.

The library is decoupled from the other Django components, such as the database
layer, views and templates. It relies only on Django settings, a couple of
``django.utils`` helper functions and Django's internationalization hooks (but
you're not required to be using internationalization features to use this
library).

Form objects
============

The primary way of using the ``forms`` library is to create a form object.
Do this by subclassing ``django.forms.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 use to implement "contact me" functionality on your
personal Web site.

Start with this basic ``Form`` subclass, which we'll call ``ContactForm``::

    from django import forms

    class ContactForm(forms.Form):
        subject = forms.CharField(max_length=100)
        message = forms.CharField()
        sender = forms.EmailField()
        cc_myself = forms.BooleanField(required=False)

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.

Creating ``Form`` instances
---------------------------

A ``Form`` instance is either **bound** to a set of data, or **unbound**.

    * If it's **bound** to a set of data, it's capable of validating that data
      and rendering the form as HTML with the data displayed in the HTML.

    * If it's **unbound**, it cannot do validation (because there's no data to
      validate!), but it can still render the blank form as HTML.

To create an unbound ``Form`` instance, simply instantiate the class::

    >>> f = ContactForm()

To bind data to a form, pass the data as a dictionary as the first parameter to
your ``Form`` class constructor::

    >>> data = {'subject': 'hello',
    ...         'message': 'Hi there',
    ...         'sender': 'foo@example.com',
    ...         'cc_myself': True}
    >>> f = ContactForm(data)

In this dictionary, the keys are the field names, which correspond to the
attributes in your ``Form`` class. The values are the data you're trying
to validate. These will usually be strings, but there's no requirement that
they be strings; the type of data you pass depends on the ``Field``, as we'll
see in a moment.

If you need to distinguish between bound and unbound form instances at runtime,
check the value of the form's ``is_bound`` attribute::

    >>> f = ContactForm()
    >>> f.is_bound
    False
    >>> f = ContactForm({'subject': 'hello'})
    >>> f.is_bound
    True

Note that passing an empty dictionary creates a *bound* form with empty data::

    >>> f = ContactForm({})
    >>> f.is_bound
    True

If you have a bound ``Form`` instance and want to change the data somehow, or
if you want to bind an unbound ``Form`` instance to some data, create another
``Form`` instance. There is no way to change data in a ``Form`` instance. Once
a ``Form`` instance has been created, you should consider its data immutable,
whether it has data or not.

Using forms to validate data
----------------------------

The primary task of a ``Form`` object is to validate data. With a bound
``Form`` instance, call the ``is_valid()`` method to run validation and return
a boolean designating whether the data was valid::

    >>> data = {'subject': 'hello',
    ...         'message': 'Hi there',
    ...         'sender': 'foo@example.com',
    ...         'cc_myself': True}
    >>> f = ContactForm(data)
    >>> f.is_valid()
    True

Let's try with some invalid data. In this case, ``subject`` is blank (an error,
because all fields are required by default) and ``sender`` is not a valid
e-mail address::

    >>> data = {'subject': '',
    ...         'message': 'Hi there',
    ...         'sender': 'invalid e-mail address',
    ...         'cc_myself': True}
    >>> f = ContactForm(data)
    >>> f.is_valid()
    False

Access the ``errors`` attribute to get a dictionary of error messages::

    >>> f.errors
    {'sender': [u'Enter a valid e-mail address.'], 'subject': [u'This field is required.']}

In this dictionary, the keys are the field names, and the values are lists of
Unicode strings representing the error messages. The error messages are stored
in lists because a field can have multiple error messages.

You can access ``errors`` without having to call ``is_valid()`` first. The
form's data will be validated the first time either you call ``is_valid()`` or
access ``errors``.

The validation routines will only get called once, regardless of how many times
you access ``errors`` or call ``is_valid()``. This means that if validation has
side effects, those side effects will only be triggered once.

Behavior of unbound forms
~~~~~~~~~~~~~~~~~~~~~~~~~

It's meaningless to validate a form with no data, but, for the record, here's
what happens with unbound forms::

    >>> f = ContactForm()
    >>> f.is_valid()
    False
    >>> f.errors
    {}

Accessing "clean" data
----------------------

Each ``Field`` in a ``Form`` class is responsible not only for validating data,
but also for "cleaning" it -- normalizing it to a consistent format. This is a
nice feature, because it allows data for a particular field to be input in
a variety of ways, always resulting in consistent output.

For example, ``DateField`` normalizes input into a Python ``datetime.date``
object. Regardless of whether you pass it a string in the format
``'1994-07-15'``, a ``datetime.date`` object or a number of other formats,
``DateField`` will always normalize it to a ``datetime.date`` object as long as
it's valid.

Once you've created a ``Form`` instance with a set of data and validated it,
you can access the clean data via the ``cleaned_data`` attribute of the ``Form``
object::

    >>> data = {'subject': 'hello',
    ...         'message': 'Hi there',
    ...         'sender': 'foo@example.com',
    ...         'cc_myself': True}
    >>> f = ContactForm(data)
    >>> f.is_valid()
    True
    >>> f.cleaned_data
    {'cc_myself': True, 'message': u'Hi there', 'sender': u'foo@example.com', 'subject': u'hello'}

.. note::
    **New in Django development version** The ``cleaned_data`` attribute was
    called ``clean_data`` in earlier releases.

Note that any text-based field -- such as ``CharField`` or ``EmailField`` --
always cleans the input into a Unicode string. We'll cover the encoding
implications later in this document.

If your data does *not* validate, your ``Form`` instance will not have a
``cleaned_data`` attribute::

    >>> data = {'subject': '',
    ...         'message': 'Hi there',
    ...         'sender': 'invalid e-mail address',
    ...         'cc_myself': True}
    >>> f = ContactForm(data)
    >>> f.is_valid()
    False
    >>> f.cleaned_data
    Traceback (most recent call last):
    ...
    AttributeError: 'ContactForm' object has no attribute 'cleaned_data'

``cleaned_data`` will always *only* contain a key for fields defined in the
``Form``, even if you pass extra data when you define the ``Form``. In this
example, we pass a bunch of extra fields to the ``ContactForm`` constructor,
but ``cleaned_data`` contains only the form's fields::

    >>> data = {'subject': 'hello',
    ...         'message': 'Hi there',
    ...         'sender': 'foo@example.com',
    ...         'cc_myself': True,
    ...         'extra_field_1': 'foo',
    ...         'extra_field_2': 'bar',
    ...         'extra_field_3': 'baz'}
    >>> f = ContactForm(data)
    >>> f.is_valid()
    True
    >>> f.cleaned_data # Doesn't contain extra_field_1, etc.
    {'cc_myself': True, 'message': u'Hi there', 'sender': u'foo@example.com', 'subject': u'hello'}

``cleaned_data`` will include a key and value for *all* fields defined in the
``Form``, even if the data didn't include a value for fields that are not
required. In this example, the data dictionary doesn't include a value for the
``nick_name`` field, but ``cleaned_data`` includes it, with an empty value::

    >>> class OptionalPersonForm(Form):
    ...     first_name = CharField()
    ...     last_name = CharField()
    ...     nick_name = CharField(required=False)
    >>> data = {'first_name': u'John', 'last_name': u'Lennon'}
    >>> f = OptionalPersonForm(data)
    >>> f.is_valid()
    True
    >>> f.cleaned_data
    {'nick_name': u'', 'first_name': u'John', 'last_name': u'Lennon'}

In this above example, the ``cleaned_data`` value for ``nick_name`` is set to an
empty string, because ``nick_name`` is ``CharField``, and ``CharField``\s treat
empty values as an empty string. Each field type knows what its "blank" value
is -- e.g., for ``DateField``, it's ``None`` instead of the empty string. For
full details on each field's behavior in this case, see the "Empty value" note
for each field in the "Built-in ``Field`` classes" section below.

You can write code to perform validation for particular form fields (based on
their name) or for the form as a whole (considering combinations of various
fields). More information about this is in the `Custom form and field
validation`_ section, below.

Behavior of unbound forms
~~~~~~~~~~~~~~~~~~~~~~~~~

It's meaningless to request "cleaned" data in a form with no data, but, for the
record, here's what happens with unbound forms::

    >>> f = ContactForm()
    >>> f.cleaned_data
    Traceback (most recent call last):
    ...
    AttributeError: 'ContactForm' object has no attribute 'cleaned_data'

Outputting forms as HTML
------------------------

The second task of a ``Form`` object is to render itself as HTML. To do so,
simply ``print`` it::

    >>> f = ContactForm()
    >>> print f
    <tr><th><label for="id_subject">Subject:</label></th><td><input id="id_subject" type="text" name="subject" maxlength="100" /></td></tr>
    <tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" /></td></tr>
    <tr><th><label for="id_sender">Sender:</label></th><td><input type="text" name="sender" id="id_sender" /></td></tr>
    <tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_cc_myself" /></td></tr>

If the form is bound to data, the HTML output will include that data
appropriately. For example, if a field is represented by an
``<input type="text">``, the data will be in the ``value`` attribute. If a
field is represented by an ``<input type="checkbox">``, then that HTML will
include ``checked="checked"`` if appropriate::

    >>> data = {'subject': 'hello',
    ...         'message': 'Hi there',
    ...         'sender': 'foo@example.com',
    ...         'cc_myself': True}
    >>> f = ContactForm(data)
    >>> print f
    <tr><th><label for="id_subject">Subject:</label></th><td><input id="id_subject" type="text" name="subject" maxlength="100" value="hello" /></td></tr>
    <tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" value="Hi there" /></td></tr>
    <tr><th><label for="id_sender">Sender:</label></th><td><input type="text" name="sender" id="id_sender" value="foo@example.com" /></td></tr>
    <tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_cc_myself" checked="checked" /></td></tr>

This default output is a two-column HTML table, with a ``<tr>`` for each field.
Notice the following:

    * For flexibility, the output does *not* include the ``<table>`` and
      ``</table>`` tags, nor does it include the ``<form>`` and ``</form>``
      tags or an ``<input type="submit">`` tag. It's your job to do that.

    * Each field type has a default HTML representation. ``CharField`` and
      ``EmailField`` are represented by an ``<input type="text">``.
      ``BooleanField`` is represented by an ``<input type="checkbox">``. 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 ``<label>`` tag, which points
      to the appropriate form field via its ``id``. Its ``id``, in turn, is
      generated by prepending ``'id_'`` to the field name. The ``id``
      attributes and ``<label>`` tags are included in the output by default, to
      follow best practices, but you can change that behavior.

Although ``<table>`` output is the default output style when you ``print`` a
form, other output styles are available. Each style is available as a method on
a form object, and each rendering method returns a Unicode object.

``as_p()``
~~~~~~~~~~

``Form.as_p()`` renders the form as a series of ``<p>`` tags, with each ``<p>``
containing one field::

    >>> f = ContactForm()
    >>> f.as_p()
    u'<p><label for="id_subject">Subject:</label> <input id="id_subject" type="text" name="subject" maxlength="100" /></p>\n<p><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" /></p>\n<p><label for="id_sender">Sender:</label> <input type="text" name="sender" id="id_sender" /></p>\n<p><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself" /></p>'
    >>> print f.as_p()
    <p><label for="id_subject">Subject:</label> <input id="id_subject" type="text" name="subject" maxlength="100" /></p>
    <p><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" /></p>
    <p><label for="id_sender">Sender:</label> <input type="text" name="sender" id="id_sender" /></p>
    <p><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself" /></p>

``as_ul()``
~~~~~~~~~~~

``Form.as_ul()`` renders the form as a series of ``<li>`` tags, with each
``<li>`` containing one field. It does *not* include the ``<ul>`` or ``</ul>``,
so that you can specify any HTML attributes on the ``<ul>`` for flexibility::

    >>> f = ContactForm()
    >>> f.as_ul()
    u'<li><label for="id_subject">Subject:</label> <input id="id_subject" type="text" name="subject" maxlength="100" /></li>\n<li><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" /></li>\n<li><label for="id_sender">Sender:</label> <input type="text" name="sender" id="id_sender" /></li>\n<li><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself" /></li>'
    >>> print f.as_ul()
    <li><label for="id_subject">Subject:</label> <input id="id_subject" type="text" name="subject" maxlength="100" /></li>
    <li><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" /></li>
    <li><label for="id_sender">Sender:</label> <input type="text" name="sender" id="id_sender" /></li>
    <li><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself" /></li>

``as_table()``
~~~~~~~~~~~~~~

Finally, ``Form.as_table()`` outputs the form as an HTML ``<table>``. This is
exactly the same as ``print``. In fact, when you ``print`` a form object, it
calls its ``as_table()`` method behind the scenes::

    >>> f = ContactForm()
    >>> f.as_table()
    u'<tr><th><label for="id_subject">Subject:</label></th><td><input id="id_subject" type="text" name="subject" maxlength="100" /></td></tr>\n<tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" /></td></tr>\n<tr><th><label for="id_sender">Sender:</label></th><td><input type="text" name="sender" id="id_sender" /></td></tr>\n<tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_cc_myself" /></td></tr>'
    >>> print f.as_table()
    <tr><th><label for="id_subject">Subject:</label></th><td><input id="id_subject" type="text" name="subject" maxlength="100" /></td></tr>
    <tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" /></td></tr>
    <tr><th><label for="id_sender">Sender:</label></th><td><input type="text" name="sender" id="id_sender" /></td></tr>
    <tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_cc_myself" /></td></tr>

Configuring HTML ``<label>`` tags
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

An HTML ``<label>`` tag designates which label text is associated with which
form element. This small enhancement makes forms more usable and more accessible
to assistive devices. It's always a good idea to use ``<label>`` tags.

By default, the form rendering methods include HTML ``id`` attributes on the
form elements and corresponding ``<label>`` tags around the labels. The ``id``
attribute values are generated by prepending ``id_`` to the form field names.
This behavior is configurable, though, if you want to change the ``id``
convention or remove HTML ``id`` attributes and ``<label>`` tags entirely.

Use the ``auto_id`` argument to the ``Form`` constructor to control the label
and ``id`` behavior. This argument must be ``True``, ``False`` or a string.

If ``auto_id`` is ``False``, then the form output will not include ``<label>``
tags nor ``id`` attributes::

    >>> f = ContactForm(auto_id=False)
    >>> print f.as_table()
    <tr><th>Subject:</th><td><input type="text" name="subject" maxlength="100" /></td></tr>
    <tr><th>Message:</th><td><input type="text" name="message" /></td></tr>
    <tr><th>Sender:</th><td><input type="text" name="sender" /></td></tr>
    <tr><th>Cc myself:</th><td><input type="checkbox" name="cc_myself" /></td></tr>
    >>> print f.as_ul()
    <li>Subject: <input type="text" name="subject" maxlength="100" /></li>
    <li>Message: <input type="text" name="message" /></li>
    <li>Sender: <input type="text" name="sender" /></li>
    <li>Cc myself: <input type="checkbox" name="cc_myself" /></li>
    >>> print f.as_p()
    <p>Subject: <input type="text" name="subject" maxlength="100" /></p>
    <p>Message: <input type="text" name="message" /></p>
    <p>Sender: <input type="text" name="sender" /></p>
    <p>Cc myself: <input type="checkbox" name="cc_myself" /></p>

If ``auto_id`` is set to ``True``, then the form output *will* include
``<label>`` tags and will simply use the field name as its ``id`` for each form
field::

    >>> f = ContactForm(auto_id=True)
    >>> print f.as_table()
    <tr><th><label for="subject">Subject:</label></th><td><input id="subject" type="text" name="subject" maxlength="100" /></td></tr>
    <tr><th><label for="message">Message:</label></th><td><input type="text" name="message" id="message" /></td></tr>
    <tr><th><label for="sender">Sender:</label></th><td><input type="text" name="sender" id="sender" /></td></tr>
    <tr><th><label for="cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="cc_myself" /></td></tr>
    >>> print f.as_ul()
    <li><label for="subject">Subject:</label> <input id="subject" type="text" name="subject" maxlength="100" /></li>
    <li><label for="message">Message:</label> <input type="text" name="message" id="message" /></li>
    <li><label for="sender">Sender:</label> <input type="text" name="sender" id="sender" /></li>
    <li><label for="cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="cc_myself" /></li>
    >>> print f.as_p()
    <p><label for="subject">Subject:</label> <input id="subject" type="text" name="subject" maxlength="100" /></p>
    <p><label for="message">Message:</label> <input type="text" name="message" id="message" /></p>
    <p><label for="sender">Sender:</label> <input type="text" name="sender" id="sender" /></p>
    <p><label for="cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="cc_myself" /></p>

If ``auto_id`` is set to a string containing the format character ``'%s'``,
then the form output will include ``<label>`` tags, and will generate ``id``
attributes based on the format string. For example, for a format string
``'field_%s'``, a field named ``subject`` will get the ``id`` value
``'field_subject'``. Continuing our example::

    >>> f = ContactForm(auto_id='id_for_%s')
    >>> print f.as_table()
    <tr><th><label for="id_for_subject">Subject:</label></th><td><input id="id_for_subject" type="text" name="subject" maxlength="100" /></td></tr>
    <tr><th><label for="id_for_message">Message:</label></th><td><input type="text" name="message" id="id_for_message" /></td></tr>
    <tr><th><label for="id_for_sender">Sender:</label></th><td><input type="text" name="sender" id="id_for_sender" /></td></tr>
    <tr><th><label for="id_for_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_for_cc_myself" /></td></tr>
    >>> print f.as_ul()
    <li><label for="id_for_subject">Subject:</label> <input id="id_for_subject" type="text" name="subject" maxlength="100" /></li>
    <li><label for="id_for_message">Message:</label> <input type="text" name="message" id="id_for_message" /></li>
    <li><label for="id_for_sender">Sender:</label> <input type="text" name="sender" id="id_for_sender" /></li>
    <li><label for="id_for_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_for_cc_myself" /></li>
    >>> print f.as_p()
    <p><label for="id_for_subject">Subject:</label> <input id="id_for_subject" type="text" name="subject" maxlength="100" /></p>
    <p><label for="id_for_message">Message:</label> <input type="text" name="message" id="id_for_message" /></p>
    <p><label for="id_for_sender">Sender:</label> <input type="text" name="sender" id="id_for_sender" /></p>
    <p><label for="id_for_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_for_cc_myself" /></p>

If ``auto_id`` is set to any other true value -- such as a string that doesn't
include ``%s`` -- then the library will act as if ``auto_id`` is ``True``.

By default, ``auto_id`` is set to the string ``'id_%s'``.

Normally, a colon (``:``) will be appended after any label name when a form is
rendered. It's possible to change the colon to another character, or omit it
entirely, using the ``label_suffix`` parameter::

    >>> f = ContactForm(auto_id='id_for_%s', label_suffix='')
    >>> print f.as_ul()
    <li><label for="id_for_subject">Subject</label> <input id="id_for_subject" type="text" name="subject" maxlength="100" /></li>
    <li><label for="id_for_message">Message</label> <input type="text" name="message" id="id_for_message" /></li>
    <li><label for="id_for_sender">Sender</label> <input type="text" name="sender" id="id_for_sender" /></li>
    <li><label for="id_for_cc_myself">Cc myself</label> <input type="checkbox" name="cc_myself" id="id_for_cc_myself" /></li>
    >>> f = ContactForm(auto_id='id_for_%s', label_suffix=' ->')
    >>> print f.as_ul()
    <li><label for="id_for_subject">Subject -></label> <input id="id_for_subject" type="text" name="subject" maxlength="100" /></li>
    <li><label for="id_for_message">Message -></label> <input type="text" name="message" id="id_for_message" /></li>
    <li><label for="id_for_sender">Sender -></label> <input type="text" name="sender" id="id_for_sender" /></li>
    <li><label for="id_for_cc_myself">Cc myself -></label> <input type="checkbox" name="cc_myself" id="id_for_cc_myself" /></li>

Note that the label suffix is added only if the last character of the
label isn't a punctuation character (``.``, ``!``, ``?`` or ``:``)

Notes on field ordering
~~~~~~~~~~~~~~~~~~~~~~~

In the ``as_p()``, ``as_ul()`` and ``as_table()`` shortcuts, the fields are
displayed in the order in which you define them in your form class. For
example, in the ``ContactForm`` example, the fields are defined in the order
``subject``, ``message``, ``sender``, ``cc_myself``. To reorder the HTML
output, just change the order in which those fields are listed in the class.

How errors are displayed
~~~~~~~~~~~~~~~~~~~~~~~~

If you render a bound ``Form`` object, the act of rendering will automatically
run the form's validation if it hasn't already happened, and the HTML output
will include the validation errors as a ``<ul class="errorlist">`` near the
field. The particular positioning of the error messages depends on the output
method you're using::

    >>> data = {'subject': '',
    ...         'message': 'Hi there',
    ...         'sender': 'invalid e-mail address',
    ...         'cc_myself': True}
    >>> f = ContactForm(data, auto_id=False)
    >>> print f.as_table()
    <tr><th>Subject:</th><td><ul class="errorlist"><li>This field is required.</li></ul><input type="text" name="subject" maxlength="100" /></td></tr>
    <tr><th>Message:</th><td><input type="text" name="message" value="Hi there" /></td></tr>
    <tr><th>Sender:</th><td><ul class="errorlist"><li>Enter a valid e-mail address.</li></ul><input type="text" name="sender" value="invalid e-mail address" /></td></tr>
    <tr><th>Cc myself:</th><td><input checked="checked" type="checkbox" name="cc_myself" /></td></tr>
    >>> print f.as_ul()
    <li><ul class="errorlist"><li>This field is required.</li></ul>Subject: <input type="text" name="subject" maxlength="100" /></li>
    <li>Message: <input type="text" name="message" value="Hi there" /></li>
    <li><ul class="errorlist"><li>Enter a valid e-mail address.</li></ul>Sender: <input type="text" name="sender" value="invalid e-mail address" /></li>
    <li>Cc myself: <input checked="checked" type="checkbox" name="cc_myself" /></li>
    >>> print f.as_p()
    <p><ul class="errorlist"><li>This field is required.</li></ul></p>
    <p>Subject: <input type="text" name="subject" maxlength="100" /></p>
    <p>Message: <input type="text" name="message" value="Hi there" /></p>
    <p><ul class="errorlist"><li>Enter a valid e-mail address.</li></ul></p>
    <p>Sender: <input type="text" name="sender" value="invalid e-mail address" /></p>
    <p>Cc myself: <input checked="checked" type="checkbox" name="cc_myself" /></p>

Customizing the error list format
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

By default, forms use ``django.forms.util.ErrorList`` to format validation
errors. If you'd like to use an alternate class for displaying errors, you can
pass that in at construction time::

    >>> from django.forms.util import ErrorList
    >>> class DivErrorList(ErrorList):
    ...     def __unicode__(self):
    ...         return self.as_divs()
    ...     def as_divs(self):
    ...         if not self: return u''
    ...         return u'<div class="errorlist">%s</div>' % ''.join([u'<div class="error">%s</div>' % e for e in self])
    >>> f = ContactForm(data, auto_id=False, error_class=DivErrorList)
    >>> f.as_p()
    <div class="errorlist"><div class="error">This field is required.</div></div>
    <p>Subject: <input type="text" name="subject" maxlength="100" /></p>
    <p>Message: <input type="text" name="message" value="Hi there" /></p>
    <div class="errorlist"><div class="error">Enter a valid e-mail address.</div></div>
    <p>Sender: <input type="text" name="sender" value="invalid e-mail address" /></p>
    <p>Cc myself: <input checked="checked" type="checkbox" name="cc_myself" /></p>

More granular output
~~~~~~~~~~~~~~~~~~~~

The ``as_p()``, ``as_ul()`` and ``as_table()`` methods are simply shortcuts for
lazy developers -- they're not the only way a form object can be displayed.

To display the HTML for a single field in your form, use dictionary lookup
syntax using the field's name as the key, and print the resulting object::

    >>> f = ContactForm()
    >>> print f['subject']
    <input id="id_subject" type="text" name="subject" maxlength="100" />
    >>> print f['message']
    <input type="text" name="message" id="id_message" />
    >>> print f['sender']
    <input type="text" name="sender" id="id_sender" />
    >>> print f['cc_myself']
    <input type="checkbox" name="cc_myself" id="id_cc_myself" />

Call ``str()`` or ``unicode()`` on the field to get its rendered HTML as a
string or Unicode object, respectively::

    >>> str(f['subject'])
    '<input id="id_subject" type="text" name="subject" maxlength="100" />'
    >>> unicode(f['subject'])
    u'<input id="id_subject" type="text" name="subject" maxlength="100" />'

The field-specific output honors the form object's ``auto_id`` setting::

    >>> f = ContactForm(auto_id=False)
    >>> print f['message']
    <input type="text" name="message" />
    >>> f = ContactForm(auto_id='id_%s')
    >>> print f['message']
    <input type="text" name="message" id="id_message" />

For a field's list of errors, access the field's ``errors`` attribute. This
is a list-like object that is displayed as an HTML ``<ul class="errorlist">``
when printed::

    >>> data = {'subject': 'hi', 'message': '', 'sender': '', 'cc_myself': ''}
    >>> f = ContactForm(data, auto_id=False)
    >>> print f['message']
    <input type="text" name="message" />
    >>> f['message'].errors
    [u'This field is required.']
    >>> print f['message'].errors
    <ul class="errorlist"><li>This field is required.</li></ul>
    >>> f['subject'].errors
    []
    >>> print f['subject'].errors

    >>> str(f['subject'].errors)
    ''

Using forms in views and templates
----------------------------------

Let's put this all together and use the ``ContactForm`` example in a Django
view and template.

Simple view example
~~~~~~~~~~~~~~~~~~~

This example view displays the contact form by default and validates/processes
it if accessed via a POST request::

    def contact(request):
        if request.method == 'POST':
            form = ContactForm(request.POST)
            if form.is_valid():
                # Do form processing here...
                return HttpResponseRedirect('/url/on_success/')
        else:
            form = ContactForm()
        return render_to_response('contact.html', {'form': form})

Simple template example
~~~~~~~~~~~~~~~~~~~~~~~

The template in the above view example, ``contact.html``, is responsible for
displaying the form as HTML. To do this, we can use the techniques outlined in
the "Outputting forms as HTML" section above.

The simplest way to display a form's HTML is to use the variable on its own,
like this::

    <form method="post" action="">
    <table>{{ form }}</table>
    <input type="submit" />
    </form>

The above template code will display the form as an HTML table, using the
``form.as_table()`` method explained previously. This works because Django's
template system displays an object's ``__str__()`` value, and the ``Form``
class' ``__str__()`` method calls its ``as_table()`` method.

The following is equivalent but a bit more explicit::

    <form method="post" action="">
    <table>{{ form.as_table }}</table>
    <input type="submit" />
    </form>

``form.as_ul`` and ``form.as_p`` are also available, as you may expect.

Note that in the above two examples, we included the ``<form>``, ``<table>``
``<input type="submit" />``, ``</table>`` and ``</form>`` tags. The form
convenience methods (``as_table()``, ``as_ul()`` and ``as_p()``) do not include
that HTML.

Complex template output
~~~~~~~~~~~~~~~~~~~~~~~

As we've stressed several times, the ``as_table()``, ``as_ul()`` and ``as_p()``
methods are just shortcuts for the common case. You can also work with the
individual fields for complete template control over the form's design.

The easiest way is to iterate over the form's fields, with
``{% for field in form %}``. For example::

    <form method="post" action="">
    <dl>
    {% for field in form %}
        <dt>{{ field.label_tag }}</dt>
        <dd>{{ field }}</dd>
        {% if field.help_text %}<dd>{{ field.help_text }}</dd>{% endif %}
        {% if field.errors %}<dd class="myerrors">{{ field.errors }}</dd>{% endif %}
    {% endfor %}
    </dl>
    <input type="submit" />
    </form>

This iteration technique is useful if you want to apply the same HTML
formatting to each field, or if you don't know the names of the form fields
ahead of time. Note that the fields will be iterated over in the order in which
they're defined in the ``Form`` class.

Alternatively, you can arrange the form's fields explicitly, by name. Do that
by accessing ``{{ form.fieldname }}``, where ``fieldname`` is the field's name.
For example::

    <form method="post" action="">
    <ul class="myformclass">
        <li>{{ form.sender.label_tag }} {{ form.sender }}</li>
        <li class="helptext">{{ form.sender.help_text }}</li>
        {% if form.sender.errors %}<ul class="errorlist">{{ form.sender.errors }}</ul>{% endif %}

        <li>{{ form.subject.label_tag }} {{ form.subject }}</li>
        <li class="helptext">{{ form.subject.help_text }}</li>
        {% if form.subject.errors %}<ul class="errorlist">{{ form.subject.errors }}</ul>{% endif %}

        ...
    </ul>
    </form>

Highlighting required fields in templates
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

It's common to show a user which fields are required. Here's an example of how
to do that, using the above example modified to insert an asterisk after the
label of each required field::

    <form method="post" action="">
    <dl>
    {% for field in form %}
        <dt>{{ field.label_tag }}{% if field.field.required %}*{% endif %}</dt>
        <dd>{{ field }}</dd>
        {% if field.help_text %}<dd>{{ field.help_text }}</dd>{% endif %}
        {% if field.errors %}<dd class="myerrors">{{ field.errors }}</dd>{% endif %}
    {% endfor %}
    </dl>
    <input type="submit" />
    </form>

The ``{% if field.field.required %}*{% endif %}`` fragment is the relevant
addition here. It adds the asterisk only if the field is required.

Note that we check ``field.field.required`` and not ``field.required``. In the
template, ``field`` is a ``forms.forms.BoundField`` instance, which holds
the actual ``Field`` instance in its ``field`` attribute.

Binding uploaded files to a form
--------------------------------

**New in Django development version**

Dealing with forms that have ``FileField`` and ``ImageField`` fields
is a little more complicated than a normal form.

Firstly, in order to upload files, you'll need to make sure that your
``<form>`` element correctly defines the ``enctype`` as
``"multipart/form-data"``::

  <form enctype="multipart/form-data" method="post" action="/foo/">

Secondly, when you use the form, you need to bind the file data. File
data is handled separately to normal form data, so when your form
contains a ``FileField`` and ``ImageField``, you will need to specify
a second argument when you bind your form. So if we extend our
ContactForm to include an ``ImageField`` called ``mugshot``, we
need to bind the file data containing the mugshot image::

    # Bound form with an image field
    >>> from django.core.files.uploadedfile import SimpleUploadedFile
    >>> data = {'subject': 'hello',
    ...         'message': 'Hi there',
    ...         'sender': 'foo@example.com',
    ...         'cc_myself': True}
    >>> file_data = {'mugshot': SimpleUploadedFile('face.jpg', <file data>)}
    >>> f = ContactFormWithMugshot(data, file_data)

In practice, you will usually specify ``request.FILES`` as the source
of file data (just like you use ``request.POST`` as the source of
form data)::

    # Bound form with an image field, data from the request
    >>> f = ContactFormWithMugshot(request.POST, request.FILES)

Constructing an unbound form is the same as always -- just omit both
form data *and* file data::

    # Unbound form with a image field
    >>> f = ContactFormWithMugshot()

Testing for multipart forms
~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you're writing reusable views or templates, you may not know ahead of time
whether your form is a multipart form or not. The ``is_multipart()`` method
tells you whether the form requires multipart encoding for submission::

    >>> f = ContactFormWithMugshot()
    >>> f.is_multipart()
    True

Here's an example of how you might use this in a template::

    {% if form.is_multipart %}
        <form enctype="multipart/form-data" method="post" action="/foo/">
    {% else %}
        <form method="post" action="/foo/">
    {% endif %}
    {{ form }}
    </form>

Subclassing forms
-----------------

If you have multiple ``Form`` classes that share fields, you can use
subclassing to remove redundancy.

When you subclass a custom ``Form`` class, the resulting subclass will
include all fields of the parent class(es), followed by the fields you define
in the subclass.

In this example, ``ContactFormWithPriority`` contains all the fields from
``ContactForm``, plus an additional field, ``priority``. The ``ContactForm``
fields are ordered first::

    >>> class ContactFormWithPriority(ContactForm):
    ...     priority = forms.CharField()
    >>> f = ContactFormWithPriority(auto_id=False)
    >>> print f.as_ul()
    <li>Subject: <input type="text" name="subject" maxlength="100" /></li>
    <li>Message: <input type="text" name="message" /></li>
    <li>Sender: <input type="text" name="sender" /></li>
    <li>Cc myself: <input type="checkbox" name="cc_myself" /></li>
    <li>Priority: <input type="text" name="priority" /></li>

It's possible to subclass multiple forms, treating forms as "mix-ins." In this
example, ``BeatleForm`` subclasses both ``PersonForm`` and ``InstrumentForm``
(in that order), and its field list includes the fields from the parent
classes::

    >>> class PersonForm(Form):
    ...     first_name = CharField()
    ...     last_name = CharField()
    >>> class InstrumentForm(Form):
    ...     instrument = CharField()
    >>> class BeatleForm(PersonForm, InstrumentForm):
    ...     haircut_type = CharField()
    >>> b = BeatleForm(auto_id=False)
    >>> print b.as_ul()
    <li>First name: <input type="text" name="first_name" /></li>
    <li>Last name: <input type="text" name="last_name" /></li>
    <li>Instrument: <input type="text" name="instrument" /></li>
    <li>Haircut type: <input type="text" name="haircut_type" /></li>

Prefixes for forms
------------------

You can put several Django forms inside one ``<form>`` tag. To give each
``Form`` its own namespace, use the ``prefix`` keyword argument::

    >>> mother = PersonForm(prefix="mother")
    >>> father = PersonForm(prefix="father")
    >>> print mother.as_ul()
    <li><label for="id_mother-first_name">First name:</label> <input type="text" name="mother-first_name" id="id_mother-first_name" /></li>
    <li><label for="id_mother-last_name">Last name:</label> <input type="text" name="mother-last_name" id="id_mother-last_name" /></li>
    >>> print father.as_ul()
    <li><label for="id_father-first_name">First name:</label> <input type="text" name="father-first_name" id="id_father-first_name" /></li>
    <li><label for="id_father-last_name">Last name:</label> <input type="text" name="father-last_name" id="id_father-last_name" /></li>

Fields
======

When you create a ``Form`` class, the most important part is defining the
fields of the form. Each field has custom validation logic, along with a few
other hooks.

Although the primary way you'll use ``Field`` classes is in ``Form`` classes,
you can also instantiate them and use them directly to get a better idea of
how they work. Each ``Field`` instance has a ``clean()`` method, which takes
a single argument and either raises a ``django.forms.ValidationError``
exception or returns the clean value::

    >>> f = forms.EmailField()
    >>> f.clean('foo@example.com')
    u'foo@example.com'
    >>> f.clean(u'foo@example.com')
    u'foo@example.com'
    >>> f.clean('invalid e-mail address')
    Traceback (most recent call last):
    ...
    ValidationError: [u'Enter a valid e-mail address.']

If you've used Django's old forms/validation framework, take care in noticing
this ``ValidationError`` is different than the previous ``ValidationError``.
This one lives at ``django.forms.ValidationError`` rather than
``django.core.validators.ValidationError``.

Core field arguments
--------------------

Each ``Field`` class constructor takes at least these arguments. Some
``Field`` classes take additional, field-specific arguments, but the following
should *always* be accepted:

``required``
~~~~~~~~~~~~

By default, each ``Field`` class assumes the value is required, so if you pass
an empty value -- either ``None`` or the empty string (``""``) -- then
``clean()`` will raise a ``ValidationError`` exception::

    >>> f = forms.CharField()
    >>> f.clean('foo')
    u'foo'
    >>> f.clean('')
    Traceback (most recent call last):
    ...
    ValidationError: [u'This field is required.']
    >>> f.clean(None)
    Traceback (most recent call last):
    ...
    ValidationError: [u'This field is required.']
    >>> f.clean(' ')
    u' '
    >>> f.clean(0)
    u'0'
    >>> f.clean(True)
    u'True'
    >>> f.clean(False)
    u'False'

To specify that a field is *not* required, pass ``required=False`` to the
``Field`` constructor::

    >>> f = forms.CharField(required=False)
    >>> f.clean('foo')
    u'foo'
    >>> f.clean('')
    u''
    >>> f.clean(None)
    u''
    >>> f.clean(0)
    u'0'
    >>> f.clean(True)
    u'True'
    >>> f.clean(False)
    u'False'

If a ``Field`` has ``required=False`` and you pass ``clean()`` an empty value,
then ``clean()`` will return a *normalized* empty value rather than raising
``ValidationError``. For ``CharField``, this will be a Unicode empty string.
For other ``Field`` classes, it might be ``None``. (This varies from field to
field.)

``label``
~~~~~~~~~

The ``label`` argument lets you specify the "human-friendly" label for this
field. This is used when the ``Field`` is displayed in a ``Form``.

As explained in "Outputting forms as HTML" above, the default label for a
``Field`` is generated from the field name by converting all underscores to
spaces and upper-casing the first letter. Specify ``label`` if that default
behavior doesn't result in an adequate label.

Here's a full example ``Form`` that implements ``label`` for two of its fields.
We've specified ``auto_id=False`` to simplify the output::

    >>> class CommentForm(forms.Form):
    ...     name = forms.CharField(label='Your name')
    ...     url = forms.URLField(label='Your Web site', required=False)
    ...     comment = forms.CharField()
    >>> f = CommentForm(auto_id=False)
    >>> print f
    <tr><th>Your name:</th><td><input type="text" name="name" /></td></tr>
    <tr><th>Your Web site:</th><td><input type="text" name="url" /></td></tr>
    <tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr>

``initial``
~~~~~~~~~~~

The ``initial`` argument lets you specify the initial value to use when
rendering this ``Field`` in an unbound ``Form``.

The use-case for this is when you want to display an "empty" form in which a
field is initialized to a particular value. For example::

    >>> class CommentForm(forms.Form):
    ...     name = forms.CharField(initial='Your name')
    ...     url = forms.URLField(initial='http://')
    ...     comment = forms.CharField()
    >>> f = CommentForm(auto_id=False)
    >>> print f
    <tr><th>Name:</th><td><input type="text" name="name" value="Your name" /></td></tr>
    <tr><th>Url:</th><td><input type="text" name="url" value="http://" /></td></tr>
    <tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr>

You may be thinking, why not just pass a dictionary of the initial values as
data when displaying the form? Well, if you do that, you'll trigger validation,
and the HTML output will include any validation errors::

    >>> class CommentForm(forms.Form):
    ...     name = forms.CharField()
    ...     url = forms.URLField()
    ...     comment = forms.CharField()
    >>> default_data = {'name': 'Your name', 'url': 'http://'}
    >>> f = CommentForm(default_data, auto_id=False)
    >>> print f
    <tr><th>Name:</th><td><input type="text" name="name" value="Your name" /></td></tr>
    <tr><th>Url:</th><td><ul class="errorlist"><li>Enter a valid URL.</li></ul><input type="text" name="url" value="http://" /></td></tr>
    <tr><th>Comment:</th><td><ul class="errorlist"><li>This field is required.</li></ul><input type="text" name="comment" /></td></tr>

This is why ``initial`` values are only displayed for unbound forms. For bound
forms, the HTML output will use the bound data.

Also note that ``initial`` values are *not* used as "fallback" data in
validation if a particular field's value is not given. ``initial`` values are
*only* intended for initial form display::

    >>> class CommentForm(forms.Form):
    ...     name = forms.CharField(initial='Your name')
    ...     url = forms.URLField(initial='http://')
    ...     comment = forms.CharField()
    >>> data = {'name': '', 'url': '', 'comment': 'Foo'}
    >>> f = CommentForm(data)
    >>> f.is_valid()
    False
    # The form does *not* fall back to using the initial values.
    >>> f.errors
    {'url': [u'This field is required.'], 'name': [u'This field is required.']}

``widget``
~~~~~~~~~~

The ``widget`` argument lets you specify a ``Widget`` class to use when
rendering this ``Field``. See `Widgets`_ below for more information.

``help_text``
~~~~~~~~~~~~~

The ``help_text`` argument lets you specify descriptive text for this
``Field``. If you provide ``help_text``, it will be displayed next to the
``Field`` when the ``Field`` is rendered by one of the convenience ``Form``
methods (e.g., ``as_ul()``).

Here's a full example ``Form`` that implements ``help_text`` for two of its
fields. We've specified ``auto_id=False`` to simplify the output::

    >>> class HelpTextContactForm(forms.Form):
    ...     subject = forms.CharField(max_length=100, help_text='100 characters max.')
    ...     message = forms.CharField()
    ...     sender = forms.EmailField(help_text='A valid e-mail address, please.')
    ...     cc_myself = forms.BooleanField(required=False)
    >>> f = HelpTextContactForm(auto_id=False)
    >>> print f.as_table()
    <tr><th>Subject:</th><td><input type="text" name="subject" maxlength="100" /><br />100 characters max.</td></tr>
    <tr><th>Message:</th><td><input type="text" name="message" /></td></tr>
    <tr><th>Sender:</th><td><input type="text" name="sender" /><br />A valid e-mail address, please.</td></tr>
    <tr><th>Cc myself:</th><td><input type="checkbox" name="cc_myself" /></td></tr>
    >>> print f.as_ul()
    <li>Subject: <input type="text" name="subject" maxlength="100" /> 100 characters max.</li>
    <li>Message: <input type="text" name="message" /></li>
    <li>Sender: <input type="text" name="sender" /> A valid e-mail address, please.</li>
    <li>Cc myself: <input type="checkbox" name="cc_myself" /></li>
    >>> print f.as_p()
    <p>Subject: <input type="text" name="subject" maxlength="100" /> 100 characters max.</p>
    <p>Message: <input type="text" name="message" /></p>
    <p>Sender: <input type="text" name="sender" /> A valid e-mail address, please.</p>
    <p>Cc myself: <input type="checkbox" name="cc_myself" /></p>

``error_messages``
~~~~~~~~~~~~~~~~~~

**New in Django development version**

The ``error_messages`` argument lets you override the default messages that the
field will raise. Pass in a dictionary with keys matching the error messages you
want to override. For example, here is the default error message::

    >>> generic = forms.CharField()
    >>> generic.clean('')
    Traceback (most recent call last):
      ...
    ValidationError: [u'This field is required.']

And here is a custom error message::

    >>> name = forms.CharField(error_messages={'required': 'Please enter your name'})
    >>> name.clean('')
    Traceback (most recent call last):
      ...
    ValidationError: [u'Please enter your name']

In the `built-in Field classes`_ section below, each ``Field`` defines the
error message keys it uses.

Dynamic initial values
----------------------

The ``initial`` argument to ``Field`` (explained above) lets you hard-code the
initial value for a ``Field`` -- but what if you want to declare the initial
value at runtime? For example, you might want to fill in a ``username`` field
with the username of the current session.

To accomplish this, use the ``initial`` argument to a ``Form``. This argument,
if given, should be a dictionary mapping field names to initial values. Only
include the fields for which you're specifying an initial value; it's not
necessary to include every field in your form. For example::

    >>> class CommentForm(forms.Form):
    ...     name = forms.CharField()
    ...     url = forms.URLField()
    ...     comment = forms.CharField()
    >>> f = CommentForm(initial={'name': 'your username'}, auto_id=False)
    >>> print f
    <tr><th>Name:</th><td><input type="text" name="name" value="your username" /></td></tr>
    <tr><th>Url:</th><td><input type="text" name="url" /></td></tr>
    <tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr>
    >>> f = CommentForm(initial={'name': 'another username'}, auto_id=False)
    >>> print f
    <tr><th>Name:</th><td><input type="text" name="name" value="another username" /></td></tr>
    <tr><th>Url:</th><td><input type="text" name="url" /></td></tr>
    <tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr>

Just like the ``initial`` parameter to ``Field``, these values are only
displayed for unbound forms, and they're not used as fallback values if a
particular value isn't provided.

Finally, note that if a ``Field`` defines ``initial`` *and* you include
``initial`` when instantiating the ``Form``, then the latter ``initial`` will
have precedence. In this example, ``initial`` is provided both at the field
level and at the form instance level, and the latter gets precedence::

    >>> class CommentForm(forms.Form):
    ...     name = forms.CharField(initial='class')
    ...     url = forms.URLField()
    ...     comment = forms.CharField()
    >>> f = CommentForm(initial={'name': 'instance'}, auto_id=False)
    >>> print f
    <tr><th>Name:</th><td><input type="text" name="name" value="instance" /></td></tr>
    <tr><th>Url:</th><td><input type="text" name="url" /></td></tr>
    <tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr>

Built-in ``Field`` classes
--------------------------

Naturally, the ``forms`` library comes with a set of ``Field`` classes that
represent common validation needs. This section documents each built-in field.

For each field, we describe the default widget used if you don't specify
``widget``. We also specify the value returned when you provide an empty value
(see the section on ``required`` above to understand what that means).

``BooleanField``
~~~~~~~~~~~~~~~~

    * Default widget: ``CheckboxInput``
    * Empty value: ``False``
    * Normalizes to: A Python ``True`` or ``False`` value.
    * Validates that the check box is checked (i.e. the value is ``True``) if
      the field has ``required=True``.
    * Error message keys: ``required``

**New in Django development version:** The empty value for a ``CheckboxInput``
(and hence the standard ``BooleanField``) has changed to return ``False``
instead of ``None`` in the development version.

.. note::
    Since all ``Field`` subclasses have ``required=True`` by default, the
    validation condition here is important. If you want to include a checkbox
    in your form that can be either checked or unchecked, you must remember to
    pass in ``required=False`` when creating the ``BooleanField``.

``CharField``
~~~~~~~~~~~~~

    * Default widget: ``TextInput``
    * Empty value: ``''`` (an empty string)
    * Normalizes to: A Unicode object.
    * Validates ``max_length`` or ``min_length``, if they are provided.
      Otherwise, all inputs are valid.
    * Error message keys: ``required``, ``max_length``, ``min_length``

Has two optional arguments for validation, ``max_length`` and ``min_length``.
If provided, these arguments ensure that the string is at most or at least the
given length.

``ChoiceField``
~~~~~~~~~~~~~~~

    * Default widget: ``Select``
    * Empty value: ``''`` (an empty string)
    * Normalizes to: A Unicode object.
    * Validates that the given value exists in the list of choices.
    * Error message keys: ``required``, ``invalid_choice``

Takes one extra argument, ``choices``, which is an iterable (e.g., a list or
tuple) of 2-tuples to use as choices for this field. This argument accepts
the same formats as the ``choices`` argument to a model field. See the
`model API documentation on choices`_ for more details.

.. _model API documentation on choices: ../model-api#choices

``DateField``
~~~~~~~~~~~~~

    * Default widget: ``TextInput``
    * Empty value: ``None``
    * Normalizes to: A Python ``datetime.date`` object.
    * Validates that the given value is either a ``datetime.date``,
      ``datetime.datetime`` or string formatted in a particular date format.
    * Error message keys: ``required``, ``invalid``

Takes one optional argument, ``input_formats``, which is a list of formats used
to attempt to convert a string to a valid ``datetime.date`` object.

If no ``input_formats`` argument is provided, the default input formats are::

    '%Y-%m-%d', '%m/%d/%Y', '%m/%d/%y', # '2006-10-25', '10/25/2006', '10/25/06'
    '%b %d %Y', '%b %d, %Y',            # 'Oct 25 2006', 'Oct 25, 2006'
    '%d %b %Y', '%d %b, %Y',            # '25 Oct 2006', '25 Oct, 2006'
    '%B %d %Y', '%B %d, %Y',            # 'October 25 2006', 'October 25, 2006'
    '%d %B %Y', '%d %B, %Y',            # '25 October 2006', '25 October, 2006'

``DateTimeField``
~~~~~~~~~~~~~~~~~

    * Default widget: ``DateTimeInput``
    * Empty value: ``None``
    * Normalizes to: A Python ``datetime.datetime`` object.
    * Validates that the given value is either a ``datetime.datetime``,
      ``datetime.date`` or string formatted in a particular datetime format.
    * Error message keys: ``required``, ``invalid``

Takes one optional argument, ``input_formats``, which is a list of formats used
to attempt to convert a string to a valid ``datetime.datetime`` object.

If no ``input_formats`` argument is provided, the default input formats are::

    '%Y-%m-%d %H:%M:%S',     # '2006-10-25 14:30:59'
    '%Y-%m-%d %H:%M',        # '2006-10-25 14:30'
    '%Y-%m-%d',              # '2006-10-25'
    '%m/%d/%Y %H:%M:%S',     # '10/25/2006 14:30:59'
    '%m/%d/%Y %H:%M',        # '10/25/2006 14:30'
    '%m/%d/%Y',              # '10/25/2006'
    '%m/%d/%y %H:%M:%S',     # '10/25/06 14:30:59'
    '%m/%d/%y %H:%M',        # '10/25/06 14:30'
    '%m/%d/%y',              # '10/25/06'

**New in Django development version:** The ``DateTimeField`` used to use a
``TextInput`` widget by default. This has now changed.

``DecimalField``
~~~~~~~~~~~~~~~~

**New in Django development version**

    * Default widget: ``TextInput``
    * Empty value: ``None``
    * Normalizes to: A Python ``decimal``.
    * Validates that the given value is a decimal. Leading and trailing
      whitespace is ignored.
    * Error message keys: ``required``, ``invalid``, ``max_value``,
      ``min_value``, ``max_digits``, ``max_decimal_places``,
      ``max_whole_digits``

Takes four optional arguments: ``max_value``, ``min_value``, ``max_digits``,
and ``decimal_places``. The first two define the limits for the fields value.
``max_digits`` is the maximum number of digits (those before the decimal
point plus those after the decimal point, with leading zeros stripped)
permitted in the value, whilst ``decimal_places`` is the maximum number of
decimal places permitted.

``EmailField``
~~~~~~~~~~~~~~

    * Default widget: ``TextInput``
    * Empty value: ``''`` (an empty string)
    * Normalizes to: A Unicode object.
    * Validates that the given value is a valid e-mail address, using a
      moderately complex regular expression.
    * Error message keys: ``required``, ``invalid``

Has two optional arguments for validation, ``max_length`` and ``min_length``.
If provided, these arguments ensure that the string is at most or at least the
given length.

``FileField``
~~~~~~~~~~~~~

**New in Django development version**

    * Default widget: ``FileInput``
    * Empty value: ``None``
    * Normalizes to: An ``UploadedFile`` object that wraps the file content
      and file name into a single object.
    * Validates that non-empty file data has been bound to the form.
    * Error message keys: ``required``, ``invalid``, ``missing``, ``empty``

To learn more about the ``UploadedFile`` object, see the `file uploads documentation`_.

When you use a ``FileField`` in a form, you must also remember to
`bind the file data to the form`_.

.. _file uploads documentation: ../upload_handling/
.. _`bind the file data to the form`: `Binding uploaded files to a form`_

``FilePathField``
~~~~~~~~~~~~~~~~~

**New in Django development version**

    * Default widget: ``Select``
    * Empty value: ``None``
    * Normalizes to: A unicode object
    * Validates that the selected choice exists in the list of choices.
    * Error message keys: ``required``, ``invalid_choice``

The field allows choosing from files inside a certain directory. It takes three
extra arguments:

    ==============  ==========  ===============================================
    Argument        Required?   Description
    ==============  ==========  ===============================================
    ``path``        Yes         The absolute path to the directory whose
                                contents you want listed. This directory must
                                exist.

    ``recursive``   No          If ``False`` (the default) only the direct
                                contents of ``path`` will be offered as choices.
                                If ``True``, the directory will be descended
                                into recursively and all descendants will be
                                listed as choices.

    ``match``       No          A regular expression pattern; only files with
                                names matching this expression will be allowed
                                as choices.
    ==============  ==========  ===============================================

``FloatField``
~~~~~~~~~~~~~~

    * Default widget: ``TextInput``
    * Empty value: ``None``
    * Normalizes to: A Python float.
    * Validates that the given value is an float. Leading and trailing
      whitespace is allowed, as in Python's ``float()`` function.
    * Error message keys: ``required``, ``invalid``, ``max_value``,
      ``min_value``

Takes two optional arguments for validation, ``max_value`` and ``min_value``.
These control the range of values permitted in the field.

``ImageField``
~~~~~~~~~~~~~~

**New in Django development version**

    * Default widget: ``FileInput``
    * Empty value: ``None``
    * Normalizes to: An ``UploadedFile`` object that wraps the file content
      and file name into a single object.
    * Validates that file data has been bound to the form, and that the
      file is of an image format understood by PIL.
    * Error message keys: ``required``, ``invalid``, ``missing``, ``empty``,
      ``invalid_image``

Using an ImageField requires that the `Python Imaging Library`_ is installed.

When you use an ``ImageField`` in a form, you must also remember to
`bind the file data to the form`_.

.. _Python Imaging Library: http://www.pythonware.com/products/pil/

``IntegerField``
~~~~~~~~~~~~~~~~

    * Default widget: ``TextInput``
    * Empty value: ``None``
    * Normalizes to: A Python integer or long integer.
    * Validates that the given value is an integer. Leading and trailing
      whitespace is allowed, as in Python's ``int()`` function.
    * Error message keys: ``required``, ``invalid``, ``max_value``,
      ``min_value``

Takes two optional arguments for validation, ``max_value`` and ``min_value``.
These control the range of values permitted in the field.

``IPAddressField``
~~~~~~~~~~~~~~~~~~

    * Default widget: ``TextInput``
    * Empty value: ``''`` (an empty string)
    * Normalizes to: A Unicode object.
    * Validates that the given value is a valid IPv4 address, using a regular
      expression.
    * Error message keys: ``required``, ``invalid``

``MultipleChoiceField``
~~~~~~~~~~~~~~~~~~~~~~~

    * Default widget: ``SelectMultiple``
    * Empty value: ``[]`` (an empty list)
    * Normalizes to: A list of Unicode objects.
    * Validates that every value in the given list of values exists in the list
      of choices.
    * Error message keys: ``required``, ``invalid_choice``, ``invalid_list``

Takes one extra argument, ``choices``, which is an iterable (e.g., a list or
tuple) of 2-tuples to use as choices for this field. This argument accepts
the same formats as the ``choices`` argument to a model field. See the
`model API documentation on choices`_ for more details.

``NullBooleanField``
~~~~~~~~~~~~~~~~~~~~

    * Default widget: ``NullBooleanSelect``
    * Empty value: ``None``
    * Normalizes to: A Python ``True``, ``False`` or ``None`` value.
    * Validates nothing (i.e., it never raises a ``ValidationError``).

``RegexField``
~~~~~~~~~~~~~~

    * Default widget: ``TextInput``
    * Empty value: ``''`` (an empty string)
    * Normalizes to: A Unicode object.
    * Validates that the given value matches against a certain regular
      expression.
    * Error message keys: ``required``, ``invalid``

Takes one required argument, ``regex``, which is a regular expression specified
either as a string or a compiled regular expression object.

Also takes the following optional arguments:

    ======================  =====================================================
    Argument                Description
    ======================  =====================================================
    ``max_length``          Ensures the string has at most this many characters.
    ``min_length``          Ensures the string has at least this many characters.
    ======================  =====================================================

The optional argument ``error_message`` is also accepted for backwards
compatibility. The preferred way to provide an error message is to use the
``error_messages`` argument, passing a dictionary with ``'invalid'`` as a key
and the error message as the value.

``TimeField``
~~~~~~~~~~~~~

    * Default widget: ``TextInput``
    * Empty value: ``None``
    * Normalizes to: A Python ``datetime.time`` object.
    * Validates that the given value is either a ``datetime.time`` or string
      formatted in a particular time format.
    * Error message keys: ``required``, ``invalid``

Takes one optional argument, ``input_formats``, which is a list of formats used
to attempt to convert a string to a valid ``datetime.time`` object.

If no ``input_formats`` argument is provided, the default input formats are::

    '%H:%M:%S',     # '14:30:59'
    '%H:%M',        # '14:30'

``URLField``
~~~~~~~~~~~~

    * Default widget: ``TextInput``
    * Empty value: ``''`` (an empty string)
    * Normalizes to: A Unicode object.
    * Validates that the given value is a valid URL.
    * Error message keys: ``required``, ``invalid``, ``invalid_link``

Takes the following optional arguments:

    ========================  =====================================================
    Argument                  Description
    ========================  =====================================================
    ``max_length``            Ensures the string has at most this many characters.
    ``min_length``            Ensures the string has at least this many characters.
    ``verify_exists``         If ``True``, the validator will attempt to load the
                              given URL, raising ``ValidationError`` if the page
                              gives a 404. Defaults to ``False``.
    ``validator_user_agent``  String used as the user-agent used when checking for
                              a URL's existence. Defaults to the value of the
                              ``URL_VALIDATOR_USER_AGENT`` setting.
    ========================  =====================================================

Slightly complex built-in ``Field`` classes
-------------------------------------------

The following are not yet documented here. See the unit tests, linked-to from
the bottom of this document, for examples of their use.

``ComboField``
~~~~~~~~~~~~~~

``MultiValueField``
~~~~~~~~~~~~~~~~~~~

``SplitDateTimeField``
~~~~~~~~~~~~~~~~~~~~~~

Fields which handle relationships
---------------------------------

For representing relationships between models, two fields are
provided which can derive their choices from a ``QuerySet``, and which
place one or more model objects into the ``cleaned_data`` dictionary
of forms in which they're used. Both of these fields have an
additional required argument:

``queryset``
    A ``QuerySet`` of model objects from which the choices for the
    field will be derived, and which will be used to validate the
    user's selection.

``ModelChoiceField``
~~~~~~~~~~~~~~~~~~~~

Allows the selection of a single model object, suitable for
representing a foreign key.

The ``__unicode__`` method of the model will be called to generate
string representations of the objects for use in the field's choices;
to provide customized representations, subclass ``ModelChoiceField``
and override ``label_from_instance``. This method will receive a model
object, and should return a string suitable for representing it. For
example::

    class MyModelChoiceField(ModelChoiceField):
        def label_from_instance(self, obj):
            return "My Object #%i" % obj.id

``ModelMultipleChoiceField``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Allows the selection of one or more model objects, suitable for
representing a many-to-many relation. As with ``ModelChoiceField``,
you can use ``label_from_instance`` to customize the object
representations.

Creating custom fields
----------------------

If the built-in ``Field`` classes don't meet your needs, you can easily create
custom ``Field`` classes. To do this, just create a subclass of
``django.forms.Field``. Its only requirements are that it implement a
``clean()`` method and that its ``__init__()`` method accept the core arguments
mentioned above (``required``, ``label``, ``initial``, ``widget``,
``help_text``).

Custom form and field validation
---------------------------------

Form validation happens when the data is cleaned. If you want to customize
this process, there are various places you can change, each one serving a
different purpose. Three types of cleaning methods are run during form
processing. These are normally executed when you call the ``is_valid()``
method on a form. There are other things that can trigger cleaning and
validation (accessing the ``errors`` attribute or calling ``full_clean()``
directly), but normally they won't be needed.

In general, any cleaning method can raise ``ValidationError`` if there is a
problem with the data it is processing, passing the relevant error message to
the ``ValidationError`` constructor. If no ``ValidationError`` is raised, the
method should return the cleaned (normalized) data as a Python object.

If you detect multiple errors during a cleaning method and wish to signal all
of them to the form submitter, it is possible to pass a list of errors to the
``ValidationError`` constructor.

The three types of cleaning methods are:

    * The ``clean()`` method on a Field subclass. This is responsible
      for cleaning the data in a way that is generic for that type of field.
      For example, a FloatField will turn the data into a Python ``float`` or
      raise a ``ValidationError``.

    * The ``clean_<fieldname>()`` method in a form subclass -- where
      ``<fieldname>`` is replaced with the name of the form field attribute.
      This method does any cleaning that is specific to that particular
      attribute, unrelated to the type of field that it is. This method is not
      passed any parameters. You will need to look up the value of the field
      in ``self.cleaned_data`` and remember that it will be a Python object
      at this point, not the original string submitted in the form (it will be
      in ``cleaned_data`` because the general field ``clean()`` method, above,
      has already cleaned the data once).

      For example, if you wanted to validate that the contents of a
      ``CharField`` called ``serialnumber`` was unique,
      ``clean_serialnumber()`` would be the right place to do this. You don't
      need a specific field (it's just a ``CharField``), but you want a
      formfield-specific piece of validation and, possibly,
      cleaning/normalizing the data.

    * The Form subclass's ``clean()`` method. This method can perform
      any validation that requires access to multiple fields from the form at
      once. This is where you might put in things to check that if field ``A``
      is supplied, field ``B`` must contain a valid e-mail address and the
      like. The data that this method returns is the final ``cleaned_data``
      attribute for the form, so don't forget to return the full list of
      cleaned data if you override this method (by default, ``Form.clean()``
      just returns ``self.cleaned_data``).

      Note that any errors raised by your ``Form.clean()`` override will not
      be associated with any field in particular. They go into a special
      "field" (called ``__all__``), which you can access via the
      ``non_field_errors()`` method if you need to.

These methods are run in the order given above, one field at a time.  That is,
for each field in the form (in the order they are declared in the form
definition), the ``Field.clean()`` method (or its override) is run, then
``clean_<fieldname>()``. Finally, once those two methods are run for every
field, the ``Form.clean()`` method, or its override, is executed.

As mentioned above, any of these methods can raise a ``ValidationError``. For
any field, if the ``Field.clean()`` method raises a ``ValidationError``, any
field-specific cleaning method is not called. However, the cleaning methods
for all remaining fields are still executed.

The ``clean()`` method for the ``Form`` class or subclass is always run. If
that method raises a ``ValidationError``, ``cleaned_data`` will be an empty
dictionary.

The previous paragraph means that if you are overriding ``Form.clean()``, you
should iterate through ``self.cleaned_data.items()``, possibly considering the
``_errors`` dictionary attribute on the form as well. In this way, you will
already know which fields have passed their individual validation requirements.

A simple example
~~~~~~~~~~~~~~~~

Here's a simple example of a custom field that validates its input is a string
containing comma-separated e-mail addresses, with at least one address. We'll
keep it simple and assume e-mail validation is contained in a function called
``is_valid_email()``. The full class::

    from django import forms

    class MultiEmailField(forms.Field):
        def clean(self, value):
            if not value:
                raise forms.ValidationError('Enter at least one e-mail address.')
            emails = value.split(',')
            for email in emails:
                if not is_valid_email(email):
                    raise forms.ValidationError('%s is not a valid e-mail address.' % email)
            return emails

Let's alter the ongoing ``ContactForm`` example to demonstrate how you'd use
this in a form. Simply use ``MultiEmailField`` instead of ``forms.EmailField``,
like so::

    class ContactForm(forms.Form):
        subject = forms.CharField(max_length=100)
        message = forms.CharField()
        senders = MultiEmailField()
        cc_myself = forms.BooleanField(required=False)

Widgets
=======

A widget is Django's representation of a HTML input element. The widget
handles the rendering of the HTML, and the extraction of data from a GET/POST
dictionary that corresponds to the widget.

Django provides a representation of all the basic HTML widgets, plus some
commonly used groups of widgets:

    ============================  ===========================================
    Widget                        HTML Equivalent
    ============================  ===========================================
    ``TextInput``                 ``<input type='text' ...``
    ``PasswordInput``             ``<input type='password' ...``
    ``HiddenInput``               ``<input type='hidden' ...``
    ``MultipleHiddenInput``       Multiple ``<input type='hidden' ...``
                                  instances.
    ``FileInput``                 ``<input type='file' ...``
    ``DateTimeInput``             ``<input type='text' ...``
    ``Textarea``                  ``<textarea>...</textarea>``
    ``CheckboxInput``             ``<input type='checkbox' ...``
    ``Select``                    ``<select><option ...``
    ``NullBooleanSelect``         Select widget with options 'Unknown',
                                  'Yes' and 'No'
    ``SelectMultiple``            ``<select multiple='multiple'><option ...``
    ``RadioSelect``               ``<ul><li><input type='radio' ...``
    ``CheckboxSelectMultiple``    ``<ul><li><input type='checkbox' ...``
    ``MultiWidget``               Wrapper around multiple other widgets
    ``SplitDateTimeWidget``       Wrapper around two ``TextInput`` widgets:
                                  one for the Date, and one for the Time.
    ============================  ===========================================

**New in Django development version:** The ``DateTimeInput`` has been added
since the last release.

Specifying widgets
------------------

Whenever you specify a field on a form, Django will use a default widget
that is appropriate to the type of data that is to be displayed. To find
which widget is used on which field, see the documentation for the
built-in Field classes.

However, if you want to use a different widget for a field, you can -
just use the 'widget' argument on the field definition. For example::

    class CommentForm(forms.Form):
        name = forms.CharField()
        url = forms.URLField()
        comment = forms.CharField(widget=forms.Textarea)

This would specify a form with a comment that uses a larger Textarea widget,
rather than the default TextInput widget.

Customizing widget instances
----------------------------

When Django renders a widget as HTML, it only renders the bare minimum
HTML - Django doesn't add a class definition, or any other widget-specific
attributes. This means that all 'TextInput' widgets will appear the same
on your Web page.

If you want to make one widget look different to another, you need to
specify additional attributes for each widget. When you specify a
widget, you can provide a list of attributes that will be added to the
rendered HTML for the widget.

For example, take the following simple form::

    class CommentForm(forms.Form):
        name = forms.CharField()
        url = forms.URLField()
        comment = forms.CharField()

This form will include three default TextInput widgets, with default rendering -
no CSS class, no extra attributes. This means that the input boxes provided for
each widget will be rendered exactly the same::

    >>> f = CommentForm(auto_id=False)
    >>> f.as_table()
    <tr><th>Name:</th><td><input type="text" name="name" /></td></tr>
    <tr><th>Url:</th><td><input type="text" name="url"/></td></tr>
    <tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr>

On a real Web page, you probably don't want every widget to look the same. You
might want a larger input element for the comment, and you might want the
'name' widget to have some special CSS class. To do this, you specify a
custom widget for your fields, and specify some attributes to use
when rendering those widgets::

    class CommentForm(forms.Form):
        name = forms.CharField(
                    widget=forms.TextInput(attrs={'class':'special'}))
        url = forms.URLField()
        comment = forms.CharField(
                   widget=forms.TextInput(attrs={'size':'40'}))

Django will then include the extra attributes in the rendered output::

    >>> f = CommentForm(auto_id=False)
    >>> f.as_table()
    <tr><th>Name:</th><td><input type="text" name="name" class="special"/></td></tr>
    <tr><th>Url:</th><td><input type="text" name="url"/></td></tr>
    <tr><th>Comment:</th><td><input type="text" name="comment" size="40"/></td></tr>

Custom Widgets
--------------

When you start to write a lot of forms, you will probably find that you will
reuse certain sets of widget attributes over and over again. Rather than
repeat these attribute definitions every time you need them, Django allows
you to capture those definitions as a custom widget.

For example, if you find that you are including a lot of comment fields on
forms, you could capture the idea of a ``TextInput`` with a specific
default ``size`` attribute as a custom extension to the ``TextInput`` widget::

    class CommentWidget(forms.TextInput):
        def __init__(self, *args, **kwargs):
            attrs = kwargs.setdefault('attrs',{})
            if 'size' not in attrs:
                attrs['size'] = 40
            super(CommentWidget, self).__init__(*args, **kwargs)

We allow the ``size`` attribute to be overridden by the user, but, by default,
this widget will behave as if ``attrs={'size': 40}`` was always passed into the
constructor.

Then you can use this widget in your forms::

    class CommentForm(forms.Form):
        name = forms.CharField()
        url = forms.URLField()
        comment = forms.CharField(widget=CommentWidget)

You can even customize your custom widget, in the same way as you would
any other widget. Adding a once-off class to your ``CommentWidget`` is as
simple as adding an attribute definition::

    class CommentForm(forms.Form):
        name = forms.CharField(max_length=20)
        url = forms.URLField()
        comment = forms.CharField(
                    widget=CommentWidget(attrs={'class': 'special'}))

Django also makes it easy to specify a custom field type that uses your custom
widget. For example, you could define a customized field type for comments
by defining::

    class CommentInput(forms.CharField):
        widget = CommentWidget

You can then use this field whenever you have a form that requires a comment::

    class CommentForm(forms.Form):
        name = forms.CharField()
        url = forms.URLField()
        comment = CommentInput()

Generating forms for models
===========================

The prefered way of generating forms that work with models is explained in the
`ModelForms documentation`_.

Looking for the ``form_for_model`` and ``form_for_instance`` documentation?
They've been deprecated, but you can still `view the documentation`_.

.. _ModelForms documentation: ../modelforms/
.. _view the documentation: ../form_for_model/

Media
=====

Rendering an attractive and easy-to-use web form requires more than just
HTML - it also requires CSS stylesheets, and if you want to use fancy
"Web2.0" widgets, you may also need to include some JavaScript on each
page. The exact combination of CSS and JavaScript that is required for
any given page will depend upon the widgets that are in use on that page.

This is where Django media definitions come in. Django allows you to
associate different media files with the forms and widgets that require
that media. For example, if you want to use a calendar to render DateFields,
you can define a custom Calendar widget. This widget can then be associated
with the CSS and JavaScript that is required to render the calendar. When
the Calendar widget is used on a form, Django is able to identify the CSS and
JavaScript files that are required, and provide the list of file names
in a form suitable for easy inclusion on your web page.

.. admonition:: Media and Django Admin

    The Django Admin application defines a number of customized widgets
    for calendars, filtered selections, and so on. These widgets define
    media requirements, and the Django Admin uses the custom widgets
    in place of the Django defaults. The Admin templates will only include
    those media files that are required to render the widgets on any
    given page.

    If you like the widgets that the Django Admin application uses,
    feel free to use them in your own application! They're all stored
    in ``django.contrib.admin.widgets``.

.. admonition:: Which JavaScript toolkit?

    Many JavaScript toolkits exist, and many of them include widgets (such
    as calendar widgets) that can be used to enhance your application.
    Django has deliberately avoided blessing any one JavaScript toolkit.
    Each toolkit has its own relative strengths and weaknesses - use
    whichever toolkit suits your requirements. Django is able to integrate
    with any JavaScript toolkit.

Media as a static definition
----------------------------

The easiest way to define media is as a static definition. Using this method,
the media declaration is an inner class. The properties of the inner class
define the media requirements.

Here's a simple example::

    class CalendarWidget(forms.TextInput):
        class Media:
            css = {
                'all': ('pretty.css',)
            }
            js = ('animations.js', 'actions.js')

This code defines a ``CalendarWidget``, which will be based on ``TextInput``.
Every time the CalendarWidget is used on a form, that form will be directed
to include the CSS file ``pretty.css``, and the JavaScript files
``animations.js`` and ``actions.js``.

This static media definition is converted at runtime into a widget property
named ``media``. The media for a CalendarWidget instance can be retrieved
through this property::

    >>> w = CalendarWidget()
    >>> print w.media
    <link href="http://media.example.com/pretty.css" type="text/css" media="all" rel="stylesheet" />
    <script type="text/javascript" src="http://media.example.com/animations.js"></script>
    <script type="text/javascript" src="http://media.example.com/actions.js"></script>

Here's a list of all possible ``Media`` options. There are no required options.

``css``
~~~~~~~

A dictionary describing the CSS files required for various forms of output
media.

The values in the dictionary should be a tuple/list of file names. See
`the section on media paths`_ for details of how to specify paths to media
files.

.. _the section on media paths: `Paths in media definitions`_

The keys in the dictionary are the output media types. These are the same
types accepted by CSS files in media declarations: 'all', 'aural', 'braille',
'embossed', 'handheld', 'print', 'projection', 'screen', 'tty' and 'tv'. If
you need to have different stylesheets for different media types, provide
a list of CSS files for each output medium. The following example would
provide two CSS options -- one for the screen, and one for print::

    class Media:
        css = {
            'screen': ('pretty.css',),
            'print': ('newspaper.css',)
        }

If a group of CSS files are appropriate for multiple output media types,
the dictionary key can be a comma separated list of output media types.
In the following example, TV's and projectors will have the same media
requirements::

    class Media:
        css = {
            'screen': ('pretty.css',),
            'tv,projector': ('lo_res.css',),
            'print': ('newspaper.css',)
        }

If this last CSS definition were to be rendered, it would become the following HTML::

    <link href="http://media.example.com/pretty.css" type="text/css" media="screen" rel="stylesheet" />
    <link href="http://media.example.com/lo_res.css" type="text/css" media="tv,projector" rel="stylesheet" />
    <link href="http://media.example.com/newspaper.css" type="text/css" media="print" rel="stylesheet" />

``js``
~~~~~~

A tuple describing the required JavaScript files. See
`the section on media paths`_ for details of how to specify paths to media
files.

``extend``
~~~~~~~~~~

A boolean defining inheritance behavior for media declarations.

By default, any object using a static media definition will inherit all the
media associated with the parent widget. This occurs regardless of how the
parent defines its media requirements. For example, if we were to extend our
basic Calendar widget from the example above::

    class FancyCalendarWidget(CalendarWidget):
        class Media:
            css = {
                'all': ('fancy.css',)
            }
            js = ('whizbang.js',)

    >>> w = FancyCalendarWidget()
    >>> print w.media
    <link href="http://media.example.com/pretty.css" type="text/css" media="all" rel="stylesheet" />
    <link href="http://media.example.com/fancy.css" type="text/css" media="all" rel="stylesheet" />
    <script type="text/javascript" src="http://media.example.com/animations.js"></script>
    <script type="text/javascript" src="http://media.example.com/actions.js"></script>
    <script type="text/javascript" src="http://media.example.com/whizbang.js"></script>

The FancyCalendar widget inherits all the media from it's parent widget. If
you don't want media to be inherited in this way, add an ``extend=False``
declaration to the media declaration::

    class FancyCalendar(Calendar):
        class Media:
            extend = False
            css = {
                'all': ('fancy.css',)
            }
            js = ('whizbang.js',)

    >>> w = FancyCalendarWidget()
    >>> print w.media
    <link href="http://media.example.com/fancy.css" type="text/css" media="all" rel="stylesheet" />
    <script type="text/javascript" src="http://media.example.com/whizbang.js"></script>

If you require even more control over media inheritance, define your media
using a `dynamic property`_. Dynamic properties give you complete control over
which media files are inherited, and which are not.

.. _dynamic property: `Media as a dynamic property`_

Media as a dynamic property
---------------------------

If you need to perform some more sophisticated manipulation of media
requirements, you can define the media property directly. This is done
by defining a model property that returns an instance of ``forms.Media``.
The constructor for ``forms.Media`` accepts ``css`` and ``js`` keyword
arguments in the same format as that used in a static media definition.

For example, the static media definition for our Calendar Widget could
also be defined in a dynamic fashion::

    class CalendarWidget(forms.TextInput):
        def _media(self):
            return forms.Media(css={'all': ('pretty.css',)},
                               js=('animations.js', 'actions.js'))
        media = property(_media)

See the section on `Media objects`_ for more details on how to construct
return values for dynamic media properties.

Paths in media definitions
--------------------------

Paths used to specify media can be either relative or absolute. If a path
starts with '/', 'http://' or 'https://', it will be interpreted as an absolute
path, and left as-is. All other paths will be prepended with the value of
``settings.MEDIA_URL``. For example, if the MEDIA_URL for your site was
``http://media.example.com/``::

    class CalendarWidget(forms.TextInput):
        class Media:
            css = {
                'all': ('/css/pretty.css',),
            }
            js = ('animations.js', 'http://othersite.com/actions.js')

    >>> w = CalendarWidget()
    >>> print w.media
    <link href="/css/pretty.css" type="text/css" media="all" rel="stylesheet" />
    <script type="text/javascript" src="http://media.example.com/animations.js"></script>
    <script type="text/javascript" src="http://othersite.com/actions.js"></script>

Media objects
-------------

When you interrogate the media attribute of a widget or form, the value that
is returned is a ``forms.Media`` object. As we have already seen, the string
representation of a Media object is the HTML required to include media
in the ``<head>`` block of your HTML page.

However, Media objects have some other interesting properties.

Media subsets
~~~~~~~~~~~~~

If you only want media of a particular type, you can use the subscript operator
to filter out a medium of interest. For example::

    >>> w = CalendarWidget()
    >>> print w.media
    <link href="http://media.example.com/pretty.css" type="text/css" media="all" rel="stylesheet" />
    <script type="text/javascript" src="http://media.example.com/animations.js"></script>
    <script type="text/javascript" src="http://media.example.com/actions.js"></script>

    >>> print w.media['css']
    <link href="http://media.example.com/pretty.css" type="text/css" media="all" rel="stylesheet" />

When you use the subscript operator, the value that is returned is a new
Media object -- but one that only contains the media of interest.

Combining media objects
~~~~~~~~~~~~~~~~~~~~~~~

Media objects can also be added together. When two media objects are added,
the resulting Media object contains the union of the media from both files::

    class CalendarWidget(forms.TextInput):
        class Media:
            css = {
                'all': ('pretty.css',)
            }
            js = ('animations.js', 'actions.js')

    class OtherWidget(forms.TextInput):
        class Media:
            js = ('whizbang.js',)

    >>> w1 = CalendarWidget()
    >>> w2 = OtherWidget()
    >>> print w1.media + w2.media
    <link href="http://media.example.com/pretty.css" type="text/css" media="all" rel="stylesheet" />
    <script type="text/javascript" src="http://media.example.com/animations.js"></script>
    <script type="text/javascript" src="http://media.example.com/actions.js"></script>
    <script type="text/javascript" src="http://media.example.com/whizbang.js"></script>

Media on Forms
--------------

Widgets aren't the only objects that can have media definitions -- forms
can also define media. The rules for media definitions on forms are the
same as the rules for widgets: declarations can be static or dynamic;
path and inheritance rules for those declarations are exactly the same.

Regardless of whether you define a media declaration, *all* Form objects
have a media property. The default value for this property is the result
of adding the media definitions for all widgets that are part of the form::

    class ContactForm(forms.Form):
        date = DateField(widget=CalendarWidget)
        name = CharField(max_length=40, widget=OtherWidget)

    >>> f = ContactForm()
    >>> f.media
    <link href="http://media.example.com/pretty.css" type="text/css" media="all" rel="stylesheet" />
    <script type="text/javascript" src="http://media.example.com/animations.js"></script>
    <script type="text/javascript" src="http://media.example.com/actions.js"></script>
    <script type="text/javascript" src="http://media.example.com/whizbang.js"></script>

If you want to associate additional media with a form -- for example, CSS for form
layout -- simply add a media declaration to the form::

    class ContactForm(forms.Form):
        date = DateField(widget=CalendarWidget)
        name = CharField(max_length=40, widget=OtherWidget)

        class Media:
            css = {
                'all': ('layout.css',)
            }

    >>> f = ContactForm()
    >>> f.media
    <link href="http://media.example.com/pretty.css" type="text/css" media="all" rel="stylesheet" />
    <link href="http://media.example.com/layout.css" type="text/css" media="all" rel="stylesheet" />
    <script type="text/javascript" src="http://media.example.com/animations.js"></script>
    <script type="text/javascript" src="http://media.example.com/actions.js"></script>
    <script type="text/javascript" src="http://media.example.com/whizbang.js"></script>

Formsets
========

A formset is a layer of abstraction to working with multiple forms on the same
page. It can be best compared to a data grid. Let's say you have the following
form::

    >>> from django import forms
    >>> class ArticleForm(forms.Form):
    ...     title = forms.CharField()
    ...     pub_date = forms.DateField()

You might want to allow the user to create several articles at once. To create
a formset of out of an ``ArticleForm`` you would do::

    >>> from django.forms.formsets import formset_factory
    >>> ArticleFormSet = formset_factory(ArticleForm)

You now have created a formset named ``ArticleFormSet``. The formset gives you
the ability to iterate over the forms in the formset and display them as you
would with a regular form::

    >>> formset = ArticleFormSet()
    >>> for form in formset.forms:
    ...     print form.as_table()
    <tr><th><label for="id_form-0-title">Title:</label></th><td><input type="text" name="form-0-title" id="id_form-0-title" /></td></tr>
    <tr><th><label for="id_form-0-pub_date">Pub date:</label></th><td><input type="text" name="form-0-pub_date" id="id_form-0-pub_date" /></td></tr>

As you can see it only displayed one form. This is because by default the
``formset_factory`` defines one extra form. This can be controlled with the
``extra`` parameter::

    >>> ArticleFormSet = formset_factory(ArticleForm, extra=2)

Using initial data with a formset
---------------------------------

Initial data is what drives the main usability of a formset. As shown above
you can define the number of extra forms. What this means is that you are
telling the formset how many additional forms to show in addition to the
number of forms it generates from the initial data. Lets take a look at an
example::

    >>> ArticleFormSet = formset_factory(ArticleForm, extra=2)
    >>> formset = ArticleFormSet(initial=[
    ...     {'title': u'Django is now open source',
    ...      'pub_date': datetime.date.today()},
    ... ])

    >>> for form in formset.forms:
    ...     print form.as_table()
    <tr><th><label for="id_form-0-title">Title:</label></th><td><input type="text" name="form-0-title" value="Django is now open source" id="id_form-0-title" /></td></tr>
    <tr><th><label for="id_form-0-pub_date">Pub date:</label></th><td><input type="text" name="form-0-pub_date" value="2008-05-12" id="id_form-0-pub_date" /></td></tr>
    <tr><th><label for="id_form-1-title">Title:</label></th><td><input type="text" name="form-1-title" id="id_form-1-title" /></td></tr>
    <tr><th><label for="id_form-1-pub_date">Pub date:</label></th><td><input type="text" name="form-1-pub_date" id="id_form-1-pub_date" /></td></tr>
    <tr><th><label for="id_form-2-title">Title:</label></th><td><input type="text" name="form-2-title" id="id_form-2-title" /></td></tr>
    <tr><th><label for="id_form-2-pub_date">Pub date:</label></th><td><input type="text" name="form-2-pub_date" id="id_form-2-pub_date" /></td></tr>

There are now a total of three forms showing above. One for the initial data
that was passed in and two extra forms. Also note that we are passing in a
list of dictionaries as the initial data.

Limiting the maximum number of forms
------------------------------------

The ``max_num`` parameter to ``formset_factory`` gives you the ability to
force the maximum number of forms the formset will display::

    >>> ArticleFormSet = formset_factory(ArticleForm, extra=2, max_num=1)
    >>> formset = ArticleFormset()
    >>> for form in formset.forms:
    ...     print form.as_table()
    <tr><th><label for="id_form-0-title">Title:</label></th><td><input type="text" name="form-0-title" id="id_form-0-title" /></td></tr>
    <tr><th><label for="id_form-0-pub_date">Pub date:</label></th><td><input type="text" name="form-0-pub_date" id="id_form-0-pub_date" /></td></tr>

The default value of ``max_num`` is ``0`` which is the same as saying put no
limit on the number forms displayed.

Formset validation
------------------

Validation with a formset is about identical to a regular ``Form``. There is
an ``is_valid`` method on the formset to provide a convenient way to validate
each form in the formset::

    >>> ArticleFormSet = formset_factory(ArticleForm)
    >>> formset = ArticleFormSet({})
    >>> formset.is_valid()
    True

We passed in no data to the formset which is resulting in a valid form. The
formset is smart enough to ignore extra forms that were not changed. If we
attempt to provide an article, but fail to do so::

    >>> data = {
    ...     'form-TOTAL_FORMS': u'1',
    ...     'form-INITIAL_FORMS': u'1',
    ...     'form-0-title': u'Test',
    ...     'form-0-pub_date': u'',
    ... }
    >>> formset = ArticleFormSet(data)
    >>> formset.is_valid()
    False
    >>> formset.errors
    [{'pub_date': [u'This field is required.']}]

As we can see the formset properly performed validation and gave us the
expected errors.

Understanding the ManagementForm
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You may have noticed the additional data that was required in the formset's
data above. This data is coming from the ``ManagementForm``. This form is
dealt with internally to the formset. If you don't use it, it will result in
an exception::

    >>> data = {
    ...     'form-0-title': u'Test',
    ...     'form-0-pub_date': u'',
    ... }
    >>> formset = ArticleFormSet(data)
    Traceback (most recent call last):
    ...
    django.forms.util.ValidationError: [u'ManagementForm data is missing or has been tampered with']

It is used to keep track of how many form instances are being displayed. If
you are adding new forms via JavaScript, you should increment the count fields
in this form as well.

Custom formset validation
~~~~~~~~~~~~~~~~~~~~~~~~~

A formset has a ``clean`` method similar to the one on a ``Form`` class. This
is where you define your own validation that deals at the formset level::

    >>> from django.forms.formsets import BaseFormSet

    >>> class BaseArticleFormSet(BaseFormSet):
    ...     def clean(self):
    ...         raise forms.ValidationError, u'An error occured.'

    >>> ArticleFormSet = formset_factory(ArticleForm, formset=BaseArticleFormSet)
    >>> formset = ArticleFormSet({})
    >>> formset.is_valid()
    False
    >>> formset.non_form_errors()
    [u'An error occured.']

The formset ``clean`` method is called after all the ``Form.clean`` methods
have been called. The errors will be found using the ``non_form_errors()``
method on the formset.

Dealing with ordering and deletion of forms
-------------------------------------------

Common use cases with a formset is dealing with ordering and deletion of the
form instances. This has been dealt with for you. The ``formset_factory``
provides two optional parameters ``can_order`` and ``can_delete`` that will do
the extra work of adding the extra fields and providing simpler ways of
getting to that data.

``can_order``
~~~~~~~~~~~~~

Default: ``False``

Lets create a formset with the ability to order::

    >>> ArticleFormSet = formset_factory(ArticleForm, can_order=True)
    >>> formset = ArticleFormSet(initial=[
    ...     {'title': u'Article #1', 'pub_date': datetime.date(2008, 5, 10)},
    ...     {'title': u'Article #2', 'pub_date': datetime.date(2008, 5, 11)},
    ... ])
    >>> for form in formset.forms:
    ...     print form.as_table()
    <tr><th><label for="id_form-0-title">Title:</label></th><td><input type="text" name="form-0-title" value="Article #1" id="id_form-0-title" /></td></tr>
    <tr><th><label for="id_form-0-pub_date">Pub date:</label></th><td><input type="text" name="form-0-pub_date" value="2008-05-10" id="id_form-0-pub_date" /></td></tr>
    <tr><th><label for="id_form-0-ORDER">Order:</label></th><td><input type="text" name="form-0-ORDER" value="1" id="id_form-0-ORDER" /></td></tr>
    <tr><th><label for="id_form-1-title">Title:</label></th><td><input type="text" name="form-1-title" value="Article #2" id="id_form-1-title" /></td></tr>
    <tr><th><label for="id_form-1-pub_date">Pub date:</label></th><td><input type="text" name="form-1-pub_date" value="2008-05-11" id="id_form-1-pub_date" /></td></tr>
    <tr><th><label for="id_form-1-ORDER">Order:</label></th><td><input type="text" name="form-1-ORDER" value="2" id="id_form-1-ORDER" /></td></tr>
    <tr><th><label for="id_form-2-title">Title:</label></th><td><input type="text" name="form-2-title" id="id_form-2-title" /></td></tr>
    <tr><th><label for="id_form-2-pub_date">Pub date:</label></th><td><input type="text" name="form-2-pub_date" id="id_form-2-pub_date" /></td></tr>
    <tr><th><label for="id_form-2-ORDER">Order:</label></th><td><input type="text" name="form-2-ORDER" id="id_form-2-ORDER" /></td></tr>

This adds an additional field to each form. This new field is named ``ORDER``
and is an ``forms.IntegerField``. For the forms that came from the initial
data it automatically assigned them a numeric value. Lets look at what will
happen when the user changes these values::

    >>> data = {
    ...     'form-TOTAL_FORMS': u'3',
    ...     'form-INITIAL_FORMS': u'2',
    ...     'form-0-title': u'Article #1',
    ...     'form-0-pub_date': u'2008-05-10',
    ...     'form-0-ORDER': u'2',
    ...     'form-1-title': u'Article #2',
    ...     'form-1-pub_date': u'2008-05-11',
    ...     'form-1-ORDER': u'1',
    ...     'form-2-title': u'Article #3',
    ...     'form-2-pub_date': u'2008-05-01',
    ...     'form-2-ORDER': u'0',
    ... }

    >>> formset = ArticleFormSet(data, initial=[
    ...     {'title': u'Article #1', 'pub_date': datetime.date(2008, 5, 10)},
    ...     {'title': u'Article #2', 'pub_date': datetime.date(2008, 5, 11)},
    ... ])
    >>> formset.is_valid()
    True
    >>> for form in formset.ordered_forms:
    ...     print form.cleaned_data
    {'pub_date': datetime.date(2008, 5, 1), 'ORDER': 0, 'title': u'Article #3'}
    {'pub_date': datetime.date(2008, 5, 11), 'ORDER': 1, 'title': u'Article #2'}
    {'pub_date': datetime.date(2008, 5, 10), 'ORDER': 2, 'title': u'Article #1'}

``can_delete``
~~~~~~~~~~~~~~

Default: ``False``

Lets create a formset with the ability to delete::

    >>> ArticleFormSet = formset_factory(ArticleForm, can_delete=True)
    >>> formset = ArticleFormSet(initial=[
    ...     {'title': u'Article #1', 'pub_date': datetime.date(2008, 5, 10)},
    ...     {'title': u'Article #2', 'pub_date': datetime.date(2008, 5, 11)},
    ... ])
    >>> for form in formset.forms:
    ....    print form.as_table()
    <input type="hidden" name="form-TOTAL_FORMS" value="3" id="id_form-TOTAL_FORMS" /><input type="hidden" name="form-INITIAL_FORMS" value="2" id="id_form-INITIAL_FORMS" />
    <tr><th><label for="id_form-0-title">Title:</label></th><td><input type="text" name="form-0-title" value="Article #1" id="id_form-0-title" /></td></tr>
    <tr><th><label for="id_form-0-pub_date">Pub date:</label></th><td><input type="text" name="form-0-pub_date" value="2008-05-10" id="id_form-0-pub_date" /></td></tr>
    <tr><th><label for="id_form-0-DELETE">Delete:</label></th><td><input type="checkbox" name="form-0-DELETE" id="id_form-0-DELETE" /></td></tr>
    <tr><th><label for="id_form-1-title">Title:</label></th><td><input type="text" name="form-1-title" value="Article #2" id="id_form-1-title" /></td></tr>
    <tr><th><label for="id_form-1-pub_date">Pub date:</label></th><td><input type="text" name="form-1-pub_date" value="2008-05-11" id="id_form-1-pub_date" /></td></tr>
    <tr><th><label for="id_form-1-DELETE">Delete:</label></th><td><input type="checkbox" name="form-1-DELETE" id="id_form-1-DELETE" /></td></tr>
    <tr><th><label for="id_form-2-title">Title:</label></th><td><input type="text" name="form-2-title" id="id_form-2-title" /></td></tr>
    <tr><th><label for="id_form-2-pub_date">Pub date:</label></th><td><input type="text" name="form-2-pub_date" id="id_form-2-pub_date" /></td></tr>
    <tr><th><label for="id_form-2-DELETE">Delete:</label></th><td><input type="checkbox" name="form-2-DELETE" id="id_form-2-DELETE" /></td></tr>

Similar to ``can_order`` this adds a new field to each form named ``DELETE``
and is a ``forms.BooleanField``. When data comes through marking any of the
delete fields you can access them with ``deleted_forms``::

    >>> data = {
    ...     'form-TOTAL_FORMS': u'3',
    ...     'form-INITIAL_FORMS': u'2',
    ...     'form-0-title': u'Article #1',
    ...     'form-0-pub_date': u'2008-05-10',
    ...     'form-0-DELETE': u'on',
    ...     'form-1-title': u'Article #2',
    ...     'form-1-pub_date': u'2008-05-11',
    ...     'form-1-DELETE': u'',
    ...     'form-2-title': u'',
    ...     'form-2-pub_date': u'',
    ...     'form-2-DELETE': u'',
    ... }

    >>> formset = ArticleFormSet(data, initial=[
    ...     {'title': u'Article #1', 'pub_date': datetime.date(2008, 5, 10)},
    ...     {'title': u'Article #2', 'pub_date': datetime.date(2008, 5, 11)},
    ... ])
    >>> [form.cleaned_data for form in formset.deleted_forms]
    [{'DELETE': True, 'pub_date': datetime.date(2008, 5, 10), 'title': u'Article #1'}]

Adding additional fields to a formset
-------------------------------------

If you need to add additional fields to the formset this can be easily
accomplished. The formset base class provides an ``add_fields`` method. You
can simply override this method to add your own fields or even redefine the
default fields/attributes of the order and deletion fields::

    >>> class BaseArticleFormSet(BaseFormSet):
    ...     def add_fields(self, form, index):
    ...         super(BaseArticleFormSet, self).add_fields(form, index)
    ...         form.fields["my_field"] = forms.CharField()

    >>> ArticleFormSet = formset_factory(ArticleForm, formset=BaseArticleFormSet)
    >>> formset = ArticleFormSet()
    >>> for form in formset.forms:
    ...     print form.as_table()
    <tr><th><label for="id_form-0-title">Title:</label></th><td><input type="text" name="form-0-title" id="id_form-0-title" /></td></tr>
    <tr><th><label for="id_form-0-pub_date">Pub date:</label></th><td><input type="text" name="form-0-pub_date" id="id_form-0-pub_date" /></td></tr>
    <tr><th><label for="id_form-0-my_field">My field:</label></th><td><input type="text" name="form-0-my_field" id="id_form-0-my_field" /></td></tr>

Using a formset in views and templates
--------------------------------------

Using a formset inside a view is as easy as using a regular ``Form`` class.
The only thing you will want to be aware of is making sure to use the
management form inside the template. Lets look at a sample view::

    def manage_articles(request):
        ArticleFormSet = formset_factory(ArticleForm)
        if request.method == 'POST':
            formset = ArticleFormSet(request.POST, request.FILES)
            if formset.is_valid():
                # do something with the formset.cleaned_data
        else:
            formset = ArticleFormSet()
        return render_to_response('manage_articles.html', {'formset': formset})

The ``manage_articles.html`` template might look like this::

    <form method="POST" action="">
        {{ formset.management_form }}
        <table>
            {% for form in formset.forms %}
            {{ form }}
            {% endfor %}
        </table>
    </form>

However the above can be slightly shortcutted and let the formset itself deal
with the management form::

    <form method="POST" action="">
        <table>
            {{ formset }}
        </table>
    </form>

The above ends up calling the ``as_table`` method on the formset class.