Author: gwilson
Date: 2010-03-16 16:03:11 -0500 (Tue, 16 Mar 2010)
New Revision: 12799
Modified:
django/branches/releases/1.1.X/docs/ref/forms/fields.txt
Log:
[1.1.X] Fixed #10361 -- Added documentation for ComboField and MultiValueField
form fields, patch from timo.
Backport of r12798 from trunk.
Modified: django/branches/releases/1.1.X/docs/ref/forms/fields.txt
===================================================================
--- django/branches/releases/1.1.X/docs/ref/forms/fields.txt 2010-03-16
20:59:15 UTC (rev 12798)
+++ django/branches/releases/1.1.X/docs/ref/forms/fields.txt 2010-03-16
21:03:11 UTC (rev 12799)
@@ -695,7 +695,6 @@
Takes the following optional arguments:
-
.. attribute:: URLField.max_length
.. attribute:: URLField.min_length
@@ -714,12 +713,65 @@
Slightly complex built-in ``Field`` classes
-------------------------------------------
-The following are not yet documented.
+``ComboField``
+~~~~~~~~~~~~~~
.. class:: ComboField(**kwargs)
+ * Default widget: ``TextInput``
+ * Empty value: ``''`` (an empty string)
+ * Normalizes to: A Unicode object.
+ * Validates that the given value against each of the fields specified
+ as an argument to the ``ComboField``.
+ * Error message keys: ``required``, ``invalid``
+
+Takes one extra required argument:
+
+.. attribute:: ComboField.fields
+
+ The list of fields that should be used to validate the field's value (in
+ the order in which they are provided).
+
+ >>> f = ComboField(fields=[CharField(max_length=20), EmailField()])
+ >>> f.clean('t...@example.com')
+ u't...@example.com'
+ >>> f.clean('longemailaddr...@example.com')
+ Traceback (most recent call last):
+ ...
+ ValidationError: [u'Ensure this value has at most 20 characters (it
has 28).']
+
+``MultiValuefield``
+~~~~~~~~~~~~~~~~~~~
+
.. class:: MultiValueField(**kwargs)
+ * Default widget: ``TextInput``
+ * Empty value: ``''`` (an empty string)
+ * Normalizes to: the type returned by the ``compress`` method of the
subclass.
+ * Validates that the given value against each of the fields specified
+ as an argument to the ``MultiValueField``.
+ * Error message keys: ``required``, ``invalid``
+
+ This abstract field (must be subclassed) aggregates the logic of multiple
+ fields. Subclasses should not have to implement clean(). Instead, they must
+ implement compress(), which takes a list of valid values and returns a
+ "compressed" version of those values -- a single value. For example,
+ :class:`SplitDateTimeField` is a subclass which combines a time field and
+ a date field into a datetime object.
+
+Takes one extra required argument:
+
+.. attribute:: MultiValueField.fields
+
+ A list of fields which are cleaned into a single field. Each value in
+ ``clean`` is cleaned by the corresponding field in ``fields`` -- the first
+ value is cleaned by the first field, the second value is cleaned by
+ the second field, etc. Once all fields are cleaned, the list of clean
+ values is "compressed" into a single value.
+
+``SplitDateTimeField``
+~~~~~~~~~~~~~~~~~~~~~~
+
.. class:: SplitDateTimeField(**kwargs)
* Default widget: ``SplitDateTimeWidget``
@@ -782,11 +834,11 @@
.. attribute:: ModelChoiceField.empty_label
- By default the ``<select>`` widget used by ``ModelChoiceField`` will have a
- an empty choice at the top of the list. You can change the text of this
label
- (which is ``"---------"`` by default) with the ``empty_label`` attribute, or
- you can disable the empty label entirely by setting ``empty_label`` to
- ``None``::
+ By default the ``<select>`` widget used by ``ModelChoiceField`` will have a
+ an empty choice at the top of the list. You can change the text of this
+ label (which is ``"---------"`` by default) with the ``empty_label``
+ attribute, or you can disable the empty label entirely by setting
+ ``empty_label`` to ``None``::
# A custom empty label
field1 = forms.ModelChoiceField(queryset=..., empty_label="(Nothing)")
@@ -794,9 +846,9 @@
# No empty label
field2 = forms.ModelChoiceField(queryset=..., empty_label=None)
- Note that if a ``ModelChoiceField`` is required and has a default
- initial value, no empty choice is created (regardless of the value
- of ``empty_label``).
+ Note that if a ``ModelChoiceField`` is required and has a default
+ initial value, no empty choice is created (regardless of the value
+ of ``empty_label``).
The ``__unicode__`` method of the model will be called to generate
string representations of the objects for use in the field's choices;
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To post to this group, send email to django-upda...@googlegroups.com.
To unsubscribe from this group, send email to
django-updates+unsubscr...@googlegroups.com.
For more options, visit this group at
http://groups.google.com/group/django-updates?hl=en.
