Ticket #3780: newforms_field_list.patch

File newforms_field_list.patch, 7.4 KB (added by Chris Beaven, 18 years ago)
  • docs/newforms.txt

     
    859859    <tr><th>Url:</th><td><input type="text" name="url" /></td></tr>
    860860    <tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr>
    861861
     862Field types
     863-----------
     864
     865``BooleanField``
     866~~~~~~~~~~~~~~~~
     867
     868Default widget: ``CheckboxInput``
     869
     870Cleans to a Python ``True`` or ``False`` value.
     871
     872``CharField``
     873~~~~~~~~~~~~~
     874
     875Default widget: ``TextInput``
     876
     877Has two optional arguments for validation, ``max_length`` and ``min_length``
     878which if provided, ensure that the string is at most or at least the given
     879length.
     880
     881``ChoiceField``
     882~~~~~~~~~~~~~~~
     883
     884Default widget: ``Select``
     885
     886Cleans to a one of the values given in ``choices``.
     887
     888Takes one extra argument, ``choices``, which is an iterable (e.g., a list or
     889tuple) of 2-tuples to use as choices for this field.
     890
     891``ComboField``
     892~~~~~~~~~~~~~~
     893
     894Default widget: ``TextInput``
     895
     896Takes one extra argument, ``fields``, which is a list of fields which are used
     897(in order) to clean the provided value.
     898
     899``DateField``
     900~~~~~~~~~~~~~
     901
     902Default widget: ``TextInput``
     903
     904Cleans to a ``datetime.date`` object. Accepts ``datetime.datetime``,
     905``datetime.date`` and strings.
     906
     907Takes one optional argument, ``input_formats``, which is a list of formats used
     908to attempt to convert a string to a valid ``datetime.date`` object.
     909
     910If no ``input_formats`` argument is provided, the default input formats are::
     911
     912    '%Y-%m-%d', '%m/%d/%Y', '%m/%d/%y', # '2006-10-25', '10/25/2006', '10/25/06'
     913    '%b %d %Y', '%b %d, %Y',            # 'Oct 25 2006', 'Oct 25, 2006'
     914    '%d %b %Y', '%d %b, %Y',            # '25 Oct 2006', '25 Oct, 2006'
     915    '%B %d %Y', '%B %d, %Y',            # 'October 25 2006', 'October 25, 2006'
     916    '%d %B %Y', '%d %B, %Y',            # '25 October 2006', '25 October, 2006'
     917
     918``DateTimeField``
     919~~~~~~~~~~~~~~~~~
     920
     921Default widget: ``TextInput``
     922
     923Cleans to a ``datetime.datetime`` object. Accepts ``datetime.datetime``,
     924``datetime.date`` and strings.
     925
     926Takes one optional argument, ``input_formats``, which is a list of formats used
     927to attempt to convert a string to a valid ``datetime.datetime`` object.
     928
     929If no ``input_formats`` argument is provided, the default input formats are::
     930
     931    '%Y-%m-%d %H:%M:%S',     # '2006-10-25 14:30:59'
     932    '%Y-%m-%d %H:%M',        # '2006-10-25 14:30'
     933    '%Y-%m-%d',              # '2006-10-25'
     934    '%m/%d/%Y %H:%M:%S',     # '10/25/2006 14:30:59'
     935    '%m/%d/%Y %H:%M',        # '10/25/2006 14:30'
     936    '%m/%d/%Y',              # '10/25/2006'
     937    '%m/%d/%y %H:%M:%S',     # '10/25/06 14:30:59'
     938    '%m/%d/%y %H:%M',        # '10/25/06 14:30'
     939    '%m/%d/%y',              # '10/25/06'
     940
     941``EmailField``
     942~~~~~~~~~~~~~~
     943
     944Default widget: ``TextInput``
     945
     946Based on a ``RegexField``, checks that the provided string looks like a
     947valid email when cleaning.
     948
     949Has two optional arguments for validation, ``max_length`` and ``min_length``
     950which if provided, ensure that the string is at most or at least the given
     951length.
     952
     953``Field``
     954~~~~~~~~~~~~~~
     955
     956Default widget: ``TextInput``
     957
     958This is the base ``Field`` type usually not used directly.
     959
     960``IntegerField``
     961~~~~~~~~~~~~~~~~
     962
     963Default widget: ``TextInput``
     964
     965Cleans to an Python ``int`` (or ``long``) object.
     966
     967``MultiValueField``
     968~~~~~~~~~~~~~~~~~~~
     969
     970Composed of multiple ``Field``s, this is a base ``Field`` type not used
     971directly.
     972
     973Its ``clean()`` method takes a "decompressed" list of values. Each value in
     974this list is cleaned by the corresponding field -- the first value is
     975cleaned by the first field, the second value is cleaned by the second
     976field, etc. Once all fields are cleaned, the list of clean values is
     977"compressed" into a single value using a ``compress()`` method defined
     978in sub-classes.
     979
     980You'll probably want to use this with ``MultiWidget``.
     981
     982``MultipleChoiceField``
     983~~~~~~~~~~~~~~~~~~~~~~~
     984
     985Default widget: ``SelectMultiple``
     986
     987Cleans to a list of values given in ``choices`` (Takes a python ``list`` or
     988``tuple``).
     989
     990Takes one extra argument, ``choices``, which is an iterable (e.g., a list or
     991tuple) of 2-tuples to use as choices for this field.
     992
     993``NullBooleanField``
     994~~~~~~~~~~~~~~~~~~~~
     995
     996Default widget: ``NullBooleanSelect``
     997
     998Cleans to a Python ``True``, ``False`` or ``None`` value. Invalid values are
     999cleaned to ``None``.
     1000
     1001``NullBooleanField``
     1002~~~~~~~~~~~~~~~~~~~~
     1003
     1004Default widget: ``TextInput``
     1005
     1006Validates a string using a regular expression.
     1007
     1008Takes the following arguments, used during cleaning:
     1009
     1010    ======================  ===================================================
     1011    Argument                Description
     1012    ======================  ===================================================
     1013    ``regex``               Either a string or a compiled regular expression
     1014                            object used for validation. Required argument.
     1015    ``max_length``          Optional value to ensure the string has at most
     1016                            this many characters.
     1017    ``min_length``          Optional value to ensure the string has at least
     1018                            this many characters.
     1019    ``error_message``       Optional error message to return for failed
     1020                            validation. If no message is provided, a generic
     1021                            error message will be used.
     1022    ======================  ===================================================
     1023
     1024``SplitDateTimeField``
     1025~~~~~~~~~~~~~~~~~~~~~~
     1026
     1027A ``MultiValueField`` which combines a ``DateField`` and a ``TimeField`` to a
     1028single ``datetime.datetime`` object.
     1029
     1030``TimeField``
     1031~~~~~~~~~~~~~
     1032
     1033Default widget: ``TextInput``
     1034
     1035Cleans to a ``datetime.time`` object. Accepts ``datetime.time`` and string
     1036objects.
     1037
     1038Takes one optional argument, ``input_formats``, which is a list of formats used
     1039to attempt to convert a string to a valid ``datetime.date`` object.
     1040
     1041If no ``input_formats`` argument is provided, the default input formats are::
     1042
     1043    '%H:%M:%S',     # '14:30:59'
     1044    '%H:%M',        # '14:30'
     1045
     1046``EmailField``
     1047~~~~~~~~~~~~~~
     1048
     1049Default widget: ``TextInput``
     1050
     1051Based on a ``RegexField``, checks that the provided string is a valid URL
     1052when cleaning.
     1053
     1054Takes the following arguments:
     1055
     1056    ========================  =================================================
     1057    Argument                  Description
     1058    ========================  =================================================
     1059    ``max_length``            Optional value to ensure the string has at most
     1060                              this many characters.
     1061    ``min_length``            Optional value to ensure the string has at least
     1062                              this many characters.
     1063    ``verify_exists``         If ``True``, the URL given will be checked for
     1064                              existence (i.e., the URL actually loads and
     1065                              doesn't give a 404 response). Defaults to
     1066                              ``False``.
     1067    ``validator_user_agent``  Optional string used as the user-agent used when
     1068                              checking for a URL's existence. Defaults to
     1069                              ``settings.URL_VALIDATOR_USER_AGENT`` or if not
     1070                              found there,
     1071                              ``'Django (http://www.djangoproject.com/)'``.
     1072    ========================  =================================================
     1073
    8621074More coming soon
    8631075================
    8641076
Back to Top