← Back to branch summary

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

« back to all changes in this revision

Viewing changes to docs/howto/custom-model-fields.txt

  • Committer: Bazaar Package Importer
  • Author(s): Jamie Strandboge
  • Date: 2010-10-12 11:34:35 UTC
  • mfrom: (1.2.7 upstream)
  • mto: This revision was merged to the branch mainline in revision 30.
  • Revision ID: james.westby@ubuntu.com-20101012113435-9lnsrh0i3mxozbt0
Tags: upstream-1.2.3
Import upstream version 1.2.3

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/howto/custom-model-fields.txt
1
 
.. _howto-custom-model-fields:
2
 
 
3
1
===========================
4
2
Writing custom model fields
5
3
===========================
10
8
Introduction
11
9
============
12
10
 
13
 
The :ref:`model reference <topics-db-models>` documentation explains how to use
 
11
The :doc:`model reference </topics/db/models>` documentation explains how to use
14
12
Django's standard field classes -- :class:`~django.db.models.CharField`,
15
13
:class:`~django.db.models.DateField`, etc. For many purposes, those classes are
16
14
all you'll need. Sometimes, though, the Django version won't meet your precise
109
107
---------------------------
110
108
 
111
109
All of Django's fields (and when we say *fields* in this document, we always
112
 
mean model fields and not :ref:`form fields <ref-forms-fields>`) are subclasses
 
110
mean model fields and not :doc:`form fields </ref/forms/fields>`) are subclasses
113
111
of :class:`django.db.models.Field`. Most of the information that Django records
114
112
about a field is common to all fields -- name, help text, uniqueness and so
115
113
forth. Storing all that information is handled by ``Field``. We'll get into the
124
122
unimportant here). This is because the field classes aren't necessary when
125
123
you're just creating and modifying attributes. Instead, they provide the
126
124
machinery for converting between the attribute value and what is stored in the
127
 
database or sent to the :ref:`serializer <topics-serialization>`.
 
125
database or sent to the :doc:`serializer </topics/serialization>`.
128
126
 
129
127
Keep this in mind when creating your own custom fields. The Django ``Field``
130
128
subclass you write provides the machinery for converting between your Python
209
207
    * :attr:`~django.db.models.Field.default`
210
208
    * :attr:`~django.db.models.Field.editable`
211
209
    * :attr:`~django.db.models.Field.serialize`: If ``False``, the field will
212
 
      not be serialized when the model is passed to Django's :ref:`serializers
213
 
      <topics-serialization>`. Defaults to ``True``.
 
210
      not be serialized when the model is passed to Django's :doc:`serializers
 
211
      </topics/serialization>`. Defaults to ``True``.
214
212
    * :attr:`~django.db.models.Field.unique_for_date`
215
213
    * :attr:`~django.db.models.Field.unique_for_month`
216
214
    * :attr:`~django.db.models.Field.unique_for_year`
225
223
      inheritance. For advanced use only.
226
224
 
227
225
All of the options without an explanation in the above list have the same
228
 
meaning they do for normal Django fields. See the :ref:`field documentation
229
 
<ref-models-fields>` for examples and details.
 
226
meaning they do for normal Django fields. See the :doc:`field documentation
 
227
</ref/models/fields>` for examples and details.
230
228
 
231
229
The ``SubfieldBase`` metaclass
232
230
------------------------------
270
268
you need to ensure that it will be of the correct datatype, or that
271
269
you handle any exceptions.
272
270
 
273
 
This is especially important if you use :ref:`ModelForms
274
 
<topics-forms-modelforms>`. When saving a ModelForm, Django will use
 
271
This is especially important if you use :doc:`ModelForms
 
272
</topics/forms/modelforms>`. When saving a ModelForm, Django will use
275
273
form values to instantiate model instances. However, if the cleaned
276
274
form data can't be used as valid input to the field, the normal form
277
275
validation process will break.
611
609
:meth:`~django.forms.Field__init__` method. Normally, all you need to do is
612
610
set up a good default for the ``form_class`` argument and then delegate further
613
611
handling to the parent class. This might require you to write a custom form
614
 
field (and even a form widget). See the :ref:`forms documentation
615
 
<topics-forms-index>` for information about this, and take a look at the code in
 
612
field (and even a form widget). See the :doc:`forms documentation
 
613
</topics/forms/index>` for information about this, and take a look at the code in
616
614
:mod:`django.contrib.localflavor` for some examples of custom widgets.
617
615
 
618
616
Continuing our ongoing example, we can write the :meth:`formfield` method as::
721
719
contents and operations. This can be subclassed to customize how the file is
722
720
accessed, and what methods are available. It lives at
723
721
``django.db.models.fields.files``, and its default behavior is explained in the
724
 
:ref:`file documentation <ref-files-file>`.
 
722
:doc:`file documentation </ref/files/file>`.
725
723
 
726
724
Once a subclass of ``File`` is created, the new ``FileField`` subclass must be
727
725
told to use it. To do so, simply assign the new ``File`` subclass to the special