← Back to branch summary

~ubuntu-branches/ubuntu/quantal/python-django/quantal-security

« back to all changes in this revision

Viewing changes to docs/ref/forms/fields.txt

  • Committer: Bazaar Package Importer
  • Author(s): Chris Lamb
  • Date: 2010-05-21 07:52:55 UTC
  • mfrom: (1.3.6 upstream)
  • mto: This revision was merged to the branch mainline in revision 28.
  • Revision ID: james.westby@ubuntu.com-20100521075255-ii78v1dyfmyu3uzx
Tags: upstream-1.2
Import upstream version 1.2

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/ref/forms/fields.txt
257
257
In the `built-in Field classes`_ section below, each ``Field`` defines the
258
258
error message keys it uses.
259
259
 
 
260
``validators``
 
261
~~~~~~~~~~~~~~
 
262
 
 
263
.. versionadded:: 1.2
 
264
 
 
265
.. attribute:: Field.validators
 
266
 
 
267
The ``validators`` argument lets you provide a list of validation functions
 
268
for this field.
 
269
 
 
270
See the :ref:`validators documentation <ref-validators>` for more information.
 
271
 
 
272
``localize``
 
273
~~~~~~~~~~~~
 
274
 
 
275
.. versionadded:: 1.2
 
276
 
 
277
.. attribute:: Field.localize
 
278
 
 
279
The ``localize`` argument enables the localization of form data, input as well
 
280
as the rendered output.
 
281
 
 
282
See the :ref:`format localization <format-localization>` documentation for
 
283
more information.
 
284
 
 
285
 
260
286
Built-in ``Field`` classes
261
287
--------------------------
262
288
 
471
497
If provided, these arguments ensure that the string is at most or at least the
472
498
given length.
473
499
 
 
500
.. versionchanged:: 1.2
 
501
   The EmailField previously did not recognize e-mail addresses as valid that
 
502
   contained an IDN (Internationalized Domain Name; a domain containing
 
503
   unicode characters) domain part. This has now been corrected.
 
504
 
474
505
``FileField``
475
506
~~~~~~~~~~~~~
476
507
 
643
674
``error_messages`` argument, passing a dictionary with ``'invalid'`` as a key
644
675
and the error message as the value.
645
676
 
 
677
``SlugField``
 
678
~~~~~~~~~~~~~
 
679
 
 
680
.. class:: SlugField(**kwargs)
 
681
 
 
682
   * Default widget: ``TextInput``
 
683
   * Empty value: ``''`` (an empty string)
 
684
   * Normalizes to: A Unicode object.
 
685
   * Validates that the given value contains only letters, numbers and
 
686
     hyphens.
 
687
   * Error messages: ``required``, ``invalid``
 
688
 
 
689
This field is intended for use in representing a model
 
690
:class:`~django.db.models.SlugField` in forms.
 
691
 
646
692
``TimeField``
647
693
~~~~~~~~~~~~~
648
694
 
680
726
 
681
727
Takes the following optional arguments:
682
728
 
683
 
 
684
729
.. attribute:: URLField.max_length
685
730
.. attribute:: URLField.min_length
686
731
 
696
741
    String used as the user-agent used when checking for a URL's existence.
697
742
    Defaults to the value of the ``URL_VALIDATOR_USER_AGENT`` setting.
698
743
 
 
744
.. versionchanged:: 1.2
 
745
   The URLField previously did not recognize URLs as valid that contained an IDN
 
746
   (Internationalized Domain Name; a domain name containing unicode characters)
 
747
   domain name. This has now been corrected.
 
748
 
 
749
 
699
750
Slightly complex built-in ``Field`` classes
700
751
-------------------------------------------
701
752
 
702
 
The following are not yet documented.
 
753
``ComboField``
 
754
~~~~~~~~~~~~~~
703
755
 
704
756
.. class:: ComboField(**kwargs)
705
757
 
 
758
    * Default widget: ``TextInput``
 
759
    * Empty value: ``''`` (an empty string)
 
760
    * Normalizes to: A Unicode object.
 
761
    * Validates that the given value against each of the fields specified
 
762
      as an argument to the ``ComboField``.
 
763
    * Error message keys: ``required``, ``invalid``
 
764
 
 
765
Takes one extra required argument:
 
766
 
 
767
.. attribute:: ComboField.fields
 
768
 
 
769
    The list of fields that should be used to validate the field's value (in
 
770
    the order in which they are provided).
 
771
 
 
772
        >>> f = ComboField(fields=[CharField(max_length=20), EmailField()])
 
773
        >>> f.clean('test@example.com')
 
774
        u'test@example.com'
 
775
        >>> f.clean('longemailaddress@example.com')
 
776
        Traceback (most recent call last):
 
777
        ...
 
778
        ValidationError: [u'Ensure this value has at most 20 characters (it has 28).']
 
779
 
 
780
``MultiValuefield``
 
781
~~~~~~~~~~~~~~~~~~~
 
782
 
706
783
.. class:: MultiValueField(**kwargs)
707
784
 
 
785
    * Default widget: ``TextInput``
 
786
    * Empty value: ``''`` (an empty string)
 
787
    * Normalizes to: the type returned by the ``compress`` method of the subclass.
 
788
    * Validates that the given value against each of the fields specified
 
789
      as an argument to the ``MultiValueField``.
 
790
    * Error message keys: ``required``, ``invalid``
 
791
 
 
792
    This abstract field (must be subclassed) aggregates the logic of multiple
 
793
    fields. Subclasses should not have to implement clean(). Instead, they must
 
794
    implement compress(), which takes a list of valid values and returns a
 
795
    "compressed" version of those values -- a single value.  For example,
 
796
    :class:`SplitDateTimeField` is a subclass which combines a time field and
 
797
    a date field into a datetime object.
 
798
 
 
799
Takes one extra required argument:
 
800
 
 
801
.. attribute:: MultiValueField.fields
 
802
 
 
803
    A list of fields which are cleaned into a single field. Each value in
 
804
    ``clean`` is cleaned by the corresponding field in ``fields`` -- the first
 
805
    value is cleaned by the first field, the second value is cleaned by
 
806
    the second field, etc.  Once all fields are cleaned, the list of clean
 
807
    values is "compressed" into a single value.
 
808
 
 
809
``SplitDateTimeField``
 
810
~~~~~~~~~~~~~~~~~~~~~~
 
811
 
708
812
.. class:: SplitDateTimeField(**kwargs)
709
813
 
710
814
    * Default widget: ``SplitDateTimeWidget``
740
844
Fields which handle relationships
741
845
---------------------------------
742
846
 
743
 
For representing relationships between models, two fields are
744
 
provided which can derive their choices from a ``QuerySet``:
 
847
Two fields are available for representing relationships between
 
848
models: :class:`ModelChoiceField` and
 
849
:class:`ModelMultipleChoiceField`.  Both of these fields require a
 
850
single ``queryset`` parameter that is used to create the choices for
 
851
the field.  Upon form validation, these fields will place either one
 
852
model object (in the case of ``ModelChoiceField``) or multiple model
 
853
objects (in the case of ``ModelMultipleChoiceField``) into the
 
854
``cleaned_data`` dictionary of the form.
 
855
 
 
856
``ModelChoiceField``
 
857
~~~~~~~~~~~~~~~~~~~~
745
858
 
746
859
.. class:: ModelChoiceField(**kwargs)
747
 
.. class:: ModelMultipleChoiceField(**kwargs)
748
860
 
749
 
These fields place one or more model objects into the ``cleaned_data``
750
 
dictionary of forms in which they're used. Both of these fields have an
751
 
additional required argument:
 
861
Allows the selection of a single model object, suitable for
 
862
representing a foreign key.  A single argument is required:
752
863
 
753
864
.. attribute:: ModelChoiceField.queryset
754
865
 
756
867
    field will be derived, and which will be used to validate the
757
868
    user's selection.
758
869
 
759
 
``ModelChoiceField``
760
 
~~~~~~~~~~~~~~~~~~~~
761
 
 
762
 
Allows the selection of a single model object, suitable for
763
 
representing a foreign key.
 
870
``ModelChoiceField`` also takes one optional argument:
 
871
 
 
872
.. attribute:: ModelChoiceField.empty_label
 
873
 
 
874
    By default the ``<select>`` widget used by ``ModelChoiceField`` will have a
 
875
    an empty choice at the top of the list. You can change the text of this
 
876
    label (which is ``"---------"`` by default) with the ``empty_label``
 
877
    attribute, or you can disable the empty label entirely by setting
 
878
    ``empty_label`` to ``None``::
 
879
 
 
880
        # A custom empty label
 
881
        field1 = forms.ModelChoiceField(queryset=..., empty_label="(Nothing)")
 
882
 
 
883
        # No empty label
 
884
        field2 = forms.ModelChoiceField(queryset=..., empty_label=None)
 
885
 
 
886
    Note that if a ``ModelChoiceField`` is required and has a default
 
887
    initial value, no empty choice is created (regardless of the value
 
888
    of ``empty_label``).
764
889
 
765
890
The ``__unicode__`` method of the model will be called to generate
766
891
string representations of the objects for use in the field's choices;
773
898
        def label_from_instance(self, obj):
774
899
            return "My Object #%i" % obj.id
775
900
 
776
 
.. attribute:: ModelChoiceField.empty_label
777
 
 
778
 
   By default the ``<select>`` widget used by ``ModelChoiceField`` will have a
779
 
   an empty choice at the top of the list. You can change the text of this label
780
 
   (which is ``"---------"`` by default) with the ``empty_label`` attribute, or
781
 
   you can disable the empty label entirely by setting ``empty_label`` to
782
 
   ``None``::
783
 
 
784
 
        # A custom empty label
785
 
        field1 = forms.ModelChoiceField(queryset=..., empty_label="(Nothing)")
786
 
 
787
 
        # No empty label
788
 
        field2 = forms.ModelChoiceField(queryset=..., empty_label=None)
789
 
 
790
 
   Note that if a ``ModelChoiceField`` is required and has a default
791
 
   initial value, no empty choice is created (regardless of the value
792
 
   of ``empty_label``).
793
 
 
794
901
``ModelMultipleChoiceField``
795
902
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
796
903
 
 
904
.. class:: ModelMultipleChoiceField(**kwargs)
 
905
 
797
906
Allows the selection of one or more model objects, suitable for
798
 
representing a many-to-many relation. As with ``ModelChoiceField``,
 
907
representing a many-to-many relation. As with :class:`ModelChoiceField`,
799
908
you can use ``label_from_instance`` to customize the object
800
 
representations.
 
909
representations, and ``queryset`` is a required parameter:
 
910
 
 
911
.. attribute:: ModelMultipleChoiceField.queryset
 
912
 
 
913
    A ``QuerySet`` of model objects from which the choices for the
 
914
    field will be derived, and which will be used to validate the
 
915
    user's selection.
801
916
 
802
917
Creating custom fields
803
918
----------------------