Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Fixed #13184 -- Document the requirement that custom model fields usi…

…ng SubfieldBase should probably implement formfield. Thanks to Mark L. for the report, and to Joseph and Honza for the guidance on the solution.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@12979 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 07590ff4e856c597b32e185de1eb9f6b52fb0b1f 1 parent 442ee68
@freakboy3742 freakboy3742 authored
Showing with 22 additions and 0 deletions.
  1. +22 −0 docs/howto/custom-model-fields.txt
View
22 docs/howto/custom-model-fields.txt
@@ -261,6 +261,28 @@ For example::
This ensures that the :meth:`to_python` method, documented below, will always be
called when the attribute is initialized.
+ModelForms and custom fields
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you use :class:`~django.db.models.SubfieldBase`, :meth:`to_python`
+will be called every time an instance of the field is assigned a
+value. This means that whenever a value may be assigned to the field,
+you need to ensure that it will be of the correct datatype, or that
+you handle any exceptions.
+
+This is especially important if you use :ref:`ModelForms
+<topics-forms-modelforms>`. When saving a ModelForm, Django will use
+form values to instantiate model instances. However, if the cleaned
+form data can't be used as valid input to the field, the normal form
+validation process will break.
+
+Therefore, you must ensure that the form field used to represent your
+custom field performs whatever input validation and data cleaning is
+necessary to convert user-provided form input into a
+`to_python()`-compatible model field value. This may require writing a
+custom form field, and/or implementing the :meth:`formfield` method on
+your field to return a form field class whose `to_python()` returns the
+correct datatype.
Documenting your Custom Field
-----------------------------
Please sign in to comment.
Something went wrong with that request. Please try again.