Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Fixed #3780 -- Added first stab at 'Built-in Field classes' section t…

…o docs/newforms.txt, with help from SmileyChris and Marc Fargas

git-svn-id: http://code.djangoproject.com/svn/django/trunk@5222 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 70703a6b71a4263594c450c9f24052deb1eefc08 1 parent 0810919
Adrian Holovaty authored May 14, 2007

Showing 1 changed file with 217 additions and 8 deletions. Show diff stats Hide diff stats

  1. 225  docs/newforms.txt
225  docs/newforms.txt
@@ -481,7 +481,7 @@ field::
481 481
 If ``auto_id`` is set to a string containing the format character ``'%s'``,
482 482
 then the form output will include ``<label>`` tags, and will generate ``id``
483 483
 attributes based on the format string. For example, for a format string
484  
-``'field_%s'``, a field named ``subject`` will get the ``id``
  484
+``'field_%s'``, a field named ``subject`` will get the ``id`` value
485 485
 ``'field_subject'``. Continuing our example::
486 486
 
487 487
     >>> f = ContactForm(auto_id='id_for_%s')
@@ -520,8 +520,9 @@ How errors are displayed
520 520
 
521 521
 If you render a bound ``Form`` object, the act of rendering will automatically
522 522
 run the form's validation if it hasn't already happened, and the HTML output
523  
-will include the validation errors as a ``<ul>`` near the field. The particular
524  
-positioning of the error messages depends on the output method you're using::
  523
+will include the validation errors as a ``<ul class="errorlist">`` near the
  524
+field. The particular positioning of the error messages depends on the output
  525
+method you're using::
525 526
 
526 527
     >>> data = {'subject': '',
527 528
     ...         'message': 'Hi there',
@@ -583,7 +584,8 @@ The field-specific output honors the form object's ``auto_id`` setting::
583 584
     <input type="text" name="message" id="id_message" />
584 585
 
585 586
 For a field's list of errors, access the field's ``errors`` attribute. This
586  
-is a list-like object that is displayed as an HTML ``<ul>`` when printed::
  587
+is a list-like object that is displayed as an HTML ``<ul class="errorlist">``
  588
+when printed::
587 589
 
588 590
     >>> data = {'subject': 'hi', 'message': '', 'sender': '', 'cc_myself': ''}
589 591
     >>> f = ContactForm(data, auto_id=False)
@@ -673,7 +675,7 @@ Core field arguments
673 675
 
674 676
 Each ``Field`` class constructor takes at least these arguments. Some
675 677
 ``Field`` classes take additional, field-specific arguments, but the following
676  
-should *always* be available:
  678
+should *always* be accepted:
677 679
 
678 680
 ``required``
679 681
 ~~~~~~~~~~~~
@@ -731,7 +733,7 @@ field.)
731 733
 The ``label`` argument lets you specify the "human-friendly" label for this
732 734
 field. This is used when the ``Field`` is displayed in a ``Form``.
733 735
 
734  
-As explained in _`Outputting forms as HTML` above, the default label for a
  736
+As explained in "Outputting forms as HTML" above, the default label for a
735 737
 ``Field`` is generated from the field name by converting all underscores to
736 738
 spaces and upper-casing the first letter. Specify ``label`` if that default
737 739
 behavior doesn't result in an adequate label.
@@ -806,14 +808,15 @@ validation if a particular field's value is not given. ``initial`` values are
806 808
 ~~~~~~~~~~
807 809
 
808 810
 The ``widget`` argument lets you specify a ``Widget`` class to use when
809  
-rendering this ``Field``. See _`Widgets` below for more information.
  811
+rendering this ``Field``. See "Widgets" below for more information.
810 812
 
811 813
 ``help_text``
812 814
 ~~~~~~~~~~~~~
813 815
 
814 816
 The ``help_text`` argument lets you specify descriptive text for this
815 817
 ``Field``. If you provide ``help_text``, it will be displayed next to the
816  
-``Field`` when the ``Field`` is rendered in a ``Form``.
  818
+``Field`` when the ``Field`` is rendered by one of the convenience ``Form``
  819
+methods (e.g., ``as_ul()``).
817 820
 
818 821
 Here's a full example ``Form`` that implements ``help_text`` for two of its
819 822
 fields. We've specified ``auto_id=False`` to simplify the output::
@@ -887,6 +890,212 @@ level and at the form instance level, and the latter gets precedence::
887 890
     <tr><th>Url:</th><td><input type="text" name="url" /></td></tr>
888 891
     <tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr>
889 892
 
  893
+Built-in ``Field`` classes
  894
+--------------------------
  895
+
  896
+Naturally, the ``newforms`` library comes with a set of ``Field`` classes that
  897
+represent common validation needs. This section documents each built-in field.
  898
+
  899
+For each field, we describe the default widget used if you don't specify
  900
+``widget``. We also specify the value returned when you provide an empty value
  901
+(see the section on ``required`` above to understand what that means).
  902
+
  903
+``BooleanField``
  904
+~~~~~~~~~~~~~~~~
  905
+
  906
+    * Default widget: ``CheckboxInput``
  907
+    * Empty value: ``None``
  908
+    * Normalizes to: A Python ``True`` or ``False`` value.
  909
+    * Validates nothing (i.e., it never raises a ``ValidationError``).
  910
+
  911
+``CharField``
  912
+~~~~~~~~~~~~~
  913
+
  914
+    * Default widget: ``TextInput``
  915
+    * Empty value: ``''`` (an empty string)
  916
+    * Normalizes to: A Unicode object.
  917
+    * Validates nothing, unless ``max_length`` or ``min_length`` is provided.
  918
+
  919
+Has two optional arguments for validation, ``max_length`` and ``min_length``.
  920
+If provided, these arguments ensure that the string is at most or at least the
  921
+given length.
  922
+
  923
+``ChoiceField``
  924
+~~~~~~~~~~~~~~~
  925
+
  926
+    * Default widget: ``Select``
  927
+    * Empty value: ``''`` (an empty string)
  928
+    * Normalizes to: A Unicode object.
  929
+    * Validates that the given value exists in the list of choices.
  930
+
  931
+Takes one extra argument, ``choices``, which is an iterable (e.g., a list or
  932
+tuple) of 2-tuples to use as choices for this field.
  933
+
  934
+``DateField``
  935
+~~~~~~~~~~~~~
  936
+
  937
+    * Default widget: ``TextInput``
  938
+    * Empty value: ``None``
  939
+    * Normalizes to: A Python ``datetime.date`` object.
  940
+    * Validates that the given value is either a ``datetime.date``,
  941
+      ``datetime.datetime`` or string formatted in a particular date format.
  942
+
  943
+Takes one optional argument, ``input_formats``, which is a list of formats used
  944
+to attempt to convert a string to a valid ``datetime.date`` object.
  945
+
  946
+If no ``input_formats`` argument is provided, the default input formats are::
  947
+
  948
+    '%Y-%m-%d', '%m/%d/%Y', '%m/%d/%y', # '2006-10-25', '10/25/2006', '10/25/06'
  949
+    '%b %d %Y', '%b %d, %Y',            # 'Oct 25 2006', 'Oct 25, 2006'
  950
+    '%d %b %Y', '%d %b, %Y',            # '25 Oct 2006', '25 Oct, 2006'
  951
+    '%B %d %Y', '%B %d, %Y',            # 'October 25 2006', 'October 25, 2006'
  952
+    '%d %B %Y', '%d %B, %Y',            # '25 October 2006', '25 October, 2006'
  953
+
  954
+``DateTimeField``
  955
+~~~~~~~~~~~~~~~~~
  956
+
  957
+    * Default widget: ``TextInput``
  958
+    * Empty value: ``None``
  959
+    * Normalizes to: A Python ``datetime.datetime`` object.
  960
+    * Validates that the given value is either a ``datetime.datetime``,
  961
+      ``datetime.date`` or string formatted in a particular datetime format.
  962
+
  963
+Takes one optional argument, ``input_formats``, which is a list of formats used
  964
+to attempt to convert a string to a valid ``datetime.datetime`` object.
  965
+
  966
+If no ``input_formats`` argument is provided, the default input formats are::
  967
+
  968
+    '%Y-%m-%d %H:%M:%S',     # '2006-10-25 14:30:59'
  969
+    '%Y-%m-%d %H:%M',        # '2006-10-25 14:30'
  970
+    '%Y-%m-%d',              # '2006-10-25'
  971
+    '%m/%d/%Y %H:%M:%S',     # '10/25/2006 14:30:59'
  972
+    '%m/%d/%Y %H:%M',        # '10/25/2006 14:30'
  973
+    '%m/%d/%Y',              # '10/25/2006'
  974
+    '%m/%d/%y %H:%M:%S',     # '10/25/06 14:30:59'
  975
+    '%m/%d/%y %H:%M',        # '10/25/06 14:30'
  976
+    '%m/%d/%y',              # '10/25/06'
  977
+
  978
+``EmailField``
  979
+~~~~~~~~~~~~~~
  980
+
  981
+    * Default widget: ``TextInput``
  982
+    * Empty value: ``''`` (an empty string)
  983
+    * Normalizes to: A Unicode object.
  984
+    * Validates that the given value is a valid e-mail address, using a
  985
+      moderately complex regular expression.
  986
+
  987
+Has two optional arguments for validation, ``max_length`` and ``min_length``.
  988
+If provided, these arguments ensure that the string is at most or at least the
  989
+given length.
  990
+
  991
+``IntegerField``
  992
+~~~~~~~~~~~~~~~~
  993
+
  994
+    * Default widget: ``TextInput``
  995
+    * Empty value: ``None``
  996
+    * Normalizes to: A Python integer or long integer.
  997
+    * Validates that the given value is an integer. Leading and trailing
  998
+      whitespace is allowed, as in Python's ``int()`` function.
  999
+
  1000
+``MultipleChoiceField``
  1001
+~~~~~~~~~~~~~~~~~~~~~~~
  1002
+
  1003
+    * Default widget: ``SelectMultiple``
  1004
+    * Empty value: ``[]`` (an empty list)
  1005
+    * Normalizes to: A list of Unicode objects.
  1006
+    * Validates that every value in the given list of values exists in the list
  1007
+      of choices.
  1008
+
  1009
+Takes one extra argument, ``choices``, which is an iterable (e.g., a list or
  1010
+tuple) of 2-tuples to use as choices for this field.
  1011
+
  1012
+``NullBooleanField``
  1013
+~~~~~~~~~~~~~~~~~~~~
  1014
+
  1015
+    * Default widget: ``NullBooleanSelect``
  1016
+    * Empty value: ``None``
  1017
+    * Normalizes to: A Python ``True``, ``False`` or ``None`` value.
  1018
+    * Validates nothing (i.e., it never raises a ``ValidationError``).
  1019
+
  1020
+``RegexField``
  1021
+~~~~~~~~~~~~~~
  1022
+
  1023
+    * Default widget: ``TextInput``
  1024
+    * Empty value: ``''`` (an empty string)
  1025
+    * Normalizes to: A Unicode object.
  1026
+    * Validates that the given value matches against a certain regular
  1027
+      expression.
  1028
+
  1029
+Takes one required argument, ``regex``, which is a regular expression specified
  1030
+either as a string or a compiled regular expression object.
  1031
+
  1032
+Also takes the following optional arguments:
  1033
+
  1034
+    ======================  =====================================================
  1035
+    Argument                Description
  1036
+    ======================  =====================================================
  1037
+    ``max_length``          Ensures the string has at most this many characters.
  1038
+    ``min_length``          Ensures the string has at least this many characters.
  1039
+    ``error_message``       Error message to return for failed validation. If no
  1040
+                            message is provided, a generic error message will be
  1041
+                            used.
  1042
+    ======================  =====================================================
  1043
+
  1044
+``TimeField``
  1045
+~~~~~~~~~~~~~
  1046
+
  1047
+    * Default widget: ``TextInput``
  1048
+    * Empty value: ``None``
  1049
+    * Normalizes to: A Python ``datetime.time`` object.
  1050
+    * Validates that the given value is either a ``datetime.time`` or string
  1051
+      formatted in a particular time format.
  1052
+
  1053
+Takes one optional argument, ``input_formats``, which is a list of formats used
  1054
+to attempt to convert a string to a valid ``datetime.time`` object.
  1055
+
  1056
+If no ``input_formats`` argument is provided, the default input formats are::
  1057
+
  1058
+    '%H:%M:%S',     # '14:30:59'
  1059
+    '%H:%M',        # '14:30'
  1060
+
  1061
+``URLField``
  1062
+~~~~~~~~~~~~
  1063
+
  1064
+    * Default widget: ``TextInput``
  1065
+    * Empty value: ``''`` (an empty string)
  1066
+    * Normalizes to: A Unicode object.
  1067
+    * Validates that the given value is a valid URL.
  1068
+
  1069
+Takes the following optional arguments:
  1070
+
  1071
+    ========================  =====================================================
  1072
+    Argument                  Description
  1073
+    ========================  =====================================================
  1074
+    ``max_length``            Ensures the string has at most this many characters.
  1075
+    ``min_length``            Ensures the string has at least this many characters.
  1076
+    ``verify_exists``         If ``True``, the validator will attempt to load the
  1077
+                              given URL, raising ``ValidationError`` if the page
  1078
+                              gives a 404. Defaults to ``False``.
  1079
+    ``validator_user_agent``  String used as the user-agent used when checking for
  1080
+                              a URL's existence. Defaults to the value of the
  1081
+                              ``URL_VALIDATOR_USER_AGENT`` setting.
  1082
+    ========================  =====================================================
  1083
+
  1084
+Slightly complex built-in ``Field`` classes
  1085
+-------------------------------------------
  1086
+
  1087
+The following are not yet documented here. See the unit tests, linked-to from
  1088
+the bottom of this document, for examples of their use.
  1089
+
  1090
+``ComboField``
  1091
+~~~~~~~~~~~~~~
  1092
+
  1093
+``MultiValueField``
  1094
+~~~~~~~~~~~~~~~~~~~
  1095
+
  1096
+``SplitDateTimeField``
  1097
+~~~~~~~~~~~~~~~~~~~~~~
  1098
+
890 1099
 Creating custom fields
891 1100
 ----------------------
892 1101
 

0 notes on commit 70703a6

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