Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Copy-edited model-API docs

git-svn-id: http://code.djangoproject.com/svn/django/trunk@136 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 5e309eb6e4e140590fb4567b138325bbab7eca71 1 parent d0e5eab
@adrianholovaty adrianholovaty authored
Showing with 371 additions and 358 deletions.
  1. +371 −358 docs/model-api.txt
View
729 docs/model-api.txt
@@ -2,123 +2,124 @@
Model reference
===============
-Django's models are the bread and butter of the framework. There's a huge
-array of options available to you when defining your data models; this
-document explains all of them.
+Django's models are the bread and butter of the framework. There's a huge
+array of options available to you when defining your data models. This
+document explains them.
Options for models
==================
-A list of all possible options for a model object follows. Although there's a
-wide array of possible options, only ``fields`` is required.
+A list of all possible options for a model object follows. Although there's a
+wide array of options, only ``fields`` is required.
``admin``
A ``meta.Admin`` object; see `Admin options`_. If this field isn't given,
the object will not have an admin interface.
-
+
``db_table``
The name of the database table to use for the module::
-
+
db_table = "pizza_orders"
-
- If not given, this will use ``app_label + '_' + module_name``.
-
+
+ If this isn't given, Django will use ``app_label + '_' + module_name``.
+
``exceptions``
Names of extra exception subclasses to include in the generated module.
These exceptions are available from instance methods and from module-level
methods::
-
+
exceptions = ("DisgustingToppingsException", "BurntCrust")
-
+
``fields``
- A list of field objects; see `Field objects`_. For example::
-
+ A list of field objects. See `Field objects`_. For example::
+
fields = (
meta.CharField('customer_name', 'customer name', maxlength=15),
meta.BooleanField('use_extra_cheese', 'use extra cheese'),
meta.IntegerField('customer_type', 'customer type', choices=CUSTOMER_TYPE_CHOICES),
...
)
-
+
``get_latest_by``
- The name of a date or datetime field; if given, the module will have a
- ``get_latest()`` function which fetches the "latest" object in terms of
- that field::
-
+ The name of a ``DateField`` or ``DateTimeField``; if given, the module will
+ have a ``get_latest()`` function that fetches the "latest" object according
+ to that field::
+
get_latest_by = "order_date"
-
+
``module_constants``
- A dict of name/values to use as extra module-level constants::
-
+ A dictionary of names/values to use as extra module-level constants::
+
module_constants = {
'MEAT_TYPE_PEPPERONI' : 1,
'MEAT_TYPE_SAUSAGE' : 2,
}
-
+
``module_name``
The name of the module::
-
+
module_name = "pizza_orders"
-
- If not given this will use a lowercased version of the class name.
-
+
+ If this isn't given, Django will use a lowercased version of the class
+ name, plus "s".
+
``order_with_respect_to``
Marks this object as "orderable" with respect to the given field. This is
almost always used with related objects to allow them to be ordered with
respect to a parent object. For example, if a ``PizzaToppping`` relates to
a ``Pizza`` object, you might use::
-
+
order_with_respect_to = 'pizza_id'
-
+
to allow the toppings to be ordered with respect to the associated pizza.
-
+
``ordering``
- The default ordering for tho object::
-
+ The default ordering for the object, for use by ``get_list`` and the admin::
+
ordering = (('order_date', 'DESC'),)
-
- This is a tuple of 2-tuples; each 2-tuple is ``(field_name, ordering_type)``
- where ordering_type is either ``"ASC"`` or ``"DESC"``. You may also use the
- magic ``(None, "RANDOM")`` ordering tuple for random ordering.
-
+
+ This is a tuple of 2-tuples. Each 2-tuple is ``(field_name, ordering_type)``
+ where ordering_type is either ``"ASC"`` or ``"DESC"``. You can also use the
+ ``(None, "RANDOM")`` for random ordering.
+
``permissions``
Extra permissions to enter into the permissions table when creating this
- object. A add, delete, and change permission is automatically created for
- each object; this option specifies extra permissions::
-
- permissions = (("may_delivier_pizzas", "Can deliver pizzas"),)
-
- This is a list of 2-tuples of
+ object. A add, delete, and change permission is automatically created for
+ each object. This option specifies extra permissions::
+
+ permissions = (("can_delivier_pizzas", "Can deliver pizzas"),)
+
+ This is a list of 2-tuples of
``(permission_code, human_readable_permission_name)``.
-
+
``unique_together``
Sets of field names that, taken together, must be unique::
-
+
unique_together = (("driver_id", "restaurant_id"),)
-
+
This is a list of lists of fields that must be unique when considered
- together.
-
+ together. It's used in the Django admin.
+
``verbose_name``
A human-readable name for the object, singular::
-
+
verbose_name = "pizza"
-
- If not given, this will use a munged version of the class name:
+
+ If this isn't given, Django will use a munged version of the class name:
``CamelCase`` becomes ``camel case``.
-
+
``verbose_name_plural``
The plural name for the object::
-
+
verbose_name_plural = "stories"
-
- If not given, ``verbose_name + "s"`` will automatically be used.
-
+
+ If this isn't given, Django will use ``verbose_name + "s"``.
+
Field objects
=============
The list of fields is the most important part of a data model. Each item in
-the ``fields`` list is an instance of a ``meta.Field`` subclass, and maps to
+the ``fields`` list is an instance of a ``meta.Field`` subclass and maps to
a database field.
All field objects -- except for ``ForeignKey`` and ``ManyToManyField`` (see
@@ -130,24 +131,25 @@ contain spaces, punctuation, etc.
General field options
---------------------
-Each type of field takes a different set of options, but there are some
-options that are common to all field types. These options are:
+Each type of field takes a different set of options, but some options are
+common to all field types. These options are:
====================== ===================================================
Option Description
====================== ===================================================
- ``blank`` If ``True``, the field is allowed to be blank.
+ ``blank`` If ``True``, the field is allowed to be blank.
Note that this is different from ``null`` in that
string fields will store the empty string instead of
- ``NULL`` internally; this means that to create a
+ ``NULL`` internally. This means that to create a
field that stores nulls you must pass ``blank=True``
- and ``null=True`` .
-
- ``choices`` A list of 2-tuples to use as choices for this
- field.If this is given, instead of the standard
- field a option menu will be used, limiting choices
- to the choices given. A choices list looks like::
-
+ and ``null=True``.
+
+ ``choices`` A list of 2-tuples to use as choices for this
+ field. If this is given, Django's admin will use a
+ select box instead of the standard text field and
+ will limit choices to the choices given. A choices
+ list looks like::
+
YEAR_IN_SCHOOL_CHOICES = (
('FR', 'Freshman'),
('SO', 'Sophomore'),
@@ -155,317 +157,322 @@ options that are common to all field types. These options are:
('SR', 'Senior'),
('GR', 'Graduate'),
)
-
+
The first element in each tuple is the actual value
- to be stored; the second element is the human
- readable name for the option.
-
+ to be stored. The second element is the
+ human-readable name for the option.
+
``core`` For objects that are edited inline to a related
object. If all "core" fields in an inline-edited
object are cleared, the object will be considered to
be deleted.
-
+
It is an error to have an inline-editable
relation without at least one core field.
-
+
``db_index`` If ``True``, the SQL generator will create a database
index on this field.
-
+
``default`` The default value for the field.
-
- ``editable`` ``True`` by default, if set to ``False`` the field
- will not be editable in the admin.
-
- ``help_text`` Extra "help" text to be displayed with the field.
-
- ``null`` If ``True`` empty values in the field will be
- stored as ``NULL`` in the database.
-
- ``primary_key`` If ``True`` this field is the primary key for the
- table. You only need to use this if you don't want
+
+ ``editable`` ``True`` by default. If this is set to ``False``,
+ the field will not be editable in the admin.
+
+ ``help_text`` Extra "help" text to be displayed under the field
+ on the object's admin form.
+
+ ``null`` If ``True``, empty values in the field will be
+ stored as ``NULL`` in the database.
+
+ ``primary_key`` If ``True``, this field is the primary key for the
+ table. You only need to use this if you don't want
the standard "id" field created and used as the
primary key.
-
+
Implies ``blank=False``, ``null=False``, and
- ``unique=True``. Only one primary key is allowed
- on each object.
-
- ``radio_admin`` If ``choices`` is given, or if the field is a
- ManyToOne relation, use a radio button interface
- for the choices instead of the standard options
- menu interface.
-
- ``unique`` If ``True`` this field must be unique throughout
- the table.
-
- ``unique_for_date`` Set this to the name of a ``DateField`` or
+ ``unique=True``. Only one primary key is allowed
+ on an object.
+
+ ``radio_admin`` If ``choices`` is given, or if the field is a
+ ManyToOne relation, use a radio-button interface
+ for the choices instead of the standard select-box
+ interface.
+
+ ``unique`` If ``True``, this field must be unique throughout
+ the table. This is enforced at the database level
+ and at the Django admin-form level.
+
+ ``unique_for_date`` Set this to the name of a ``DateField`` or
``DateTimeField`` to require that this field
- be unique for the value of the date field. That
- is, if you have a field, ``title`` that has
+ be unique for the value of the date field. For
+ example, if you have a field ``title`` that has
``unique_for_date="pub_date"``, then it is an
error to have two rows with the same ``title``
and the same ``pub_date``.
-
+
``unique_for_month`` Like ``unique_for_date``, but requires the field
to be unique with respect to the month.
-
- ``unique_for_year`` Like ``unique_for_date`` and ``unique_for_month``
- but, well, you get the idea.
-
+
+ ``unique_for_year`` Like ``unique_for_date`` and ``unique_for_month``.
+
``validator_list`` A list of extra validators to apply to the field.
- See the `Form fields guide`_ for information about
- validators.
====================== ===================================================
-.. _`Form fields guide`: http://www.djangoproject.com/FIXME/
-
Field Types
-----------
-
+
``AutoField``
- An ``IntegerField`` that automatically increments. You usually won't need to
- use this directly; a primary key field will automatically be added to your
- model if you don't specify otherwise. That automatically added field is::
-
+ An ``IntegerField`` that automatically increments. You usually won't need to
+ use this directly; a primary key field will automatically be added to your
+ model if you don't specify otherwise. That automatically-added field is::
+
meta.AutoField('id', 'ID', primary_key=True)
-
+
``BooleanField``
A true/false field.
-
+
``CharField``
- A text field. These are displayed in the admin as single-line text inputs, so
- for large amounts of text use a ``TextField``.
-
- ``CharField``s have an extra required argument: ``maxlength``; the maximum
- length (in characters) of the field.
-
+ A text field. These are displayed in the admin as single-line text inputs, so
+ for large amounts of text, use a ``TextField``.
+
+ ``CharField``s have an extra required argument: ``maxlength``, the maximum
+ length (in characters) of the field. The maxlength is enforced at the database
+ level and in Django's admin validation.
+
``CommaSeparatedIntegerField``
A field of integers separated by commas.
-
+
``DateField``
- A, um, date field. Has a few extra optional options:
-
+ A date field. Has a few extra optional options:
+
====================== ===================================================
Option Description
====================== ===================================================
``auto_now`` Automatically set the field to now every time the
- object is saved. Useful for "last-modified"
+ object is saved. Useful for "last-modified"
timestamps.
-
+
``auto_now_add`` Automatically set the field to now when the object
- is first created. Useful for creation timestamps.
+ is first created. Useful for creation of
+ timestamps.
====================== ===================================================
-
+
``DateTimeField``
A date and time field. Takes the same extra options as ``DateField``.
-
-
+
``EmailField``
- A ``CharField`` that checks that the value is a valid email address. Because
- validating email addresses can be tricky, this is a pretty loose test.
-
+ A ``CharField`` that checks that the value is a valid e-mail address.
+ Because validating e-mail addresses can be tricky, this is a pretty loose
+ test.
+
``FileField``
- A file-upload field. Takes on additional option, ``upload_to`` which is
- a path to upload the file to. This path may contain `strftime formatting`_
- which will be replaced by the date/time of the file upload (so that uploaded
- files don't fill up the given directory).
-
+ A file-upload field. Takes an additional option, ``upload_to``, which is
+ a local filesystem path to upload the file to. This path may contain
+ `strftime formatting`_, which will be replaced by the date/time of the file
+ upload (so that uploaded files don't fill up the given directory).
+
.. _`strftime formatting`: http://docs.python.org/lib/module-time.html#l2h-1941
-
+
``FloatField``
- A floating-point number. Has two additional required options:
-
+ A floating-point number. Has two additional required options:
+
====================== ===================================================
Option Description
====================== ===================================================
``max_digits`` The maximum number of digits allowed in the number.
-
+
``decimal_places`` The number of decimal places to store with the
number
====================== ===================================================
-
+
For example, to store numbers up to 999 with a resolution of 2 decimal places,
you'd use::
-
+
meta.FloatField(..., max_digits=5, decimal_places=2)
-
+
And to store numbers up to one million with a resolution of 10 decimal places::
-
+
meta.FloatField(..., max_digits=19, decimal_places=10)
-
+
``ForeignKey``
- A many-to-one relationship to the primary key in another object. So, to give a
- ``Topping`` object a many-to-one relationship to ``Pizza`` (i.e. there are
+ A many-to-one relationship to the primary key in another object. So, to give a
+ ``Topping`` object a many-to-one relationship to ``Pizza`` (i.e. there are
many toppings on a pizza)::
-
+
meta.ForeignKey(Pizza)
-
+
``ForeignKey`` fields take a large number of extra options for defining how
the relationship should work:
-
+
======================= ============================================================
Option Description
======================= ============================================================
- ``edit_inline`` If ``True``, this related object is edited
- "inline" on the related object's page. This means
- that the object will not have its own admin
- interface.
-
- ``edit_inline_type`` This is either ``meta.TABULAR`` or
- ``meta.STACKED`` and controls weather the inline
+ ``edit_inline`` If ``True``, this related object is edited
+ "inline" on the related object's page. This means
+ that the object will not have its own admin
+ interface.
+
+ ``edit_inline_type`` This is either ``meta.TABULAR`` or
+ ``meta.STACKED`` and controls whether the inline
editable objects are displayed as a table or as
- a "stack" of fieldsets. Defaults to
+ a "stack" of fieldsets. Defaults to
``meta.STACKED``.
-
+
``limit_choices_to`` A dictionary of lookup arguments and values (see
- the `Database API reference`_) to limit choices
- of this object to. Use this along with
- ``meta.LazyDate`` to limit choices of objects
- by date, for example::
-
+ the `Database API reference`_) that limit the
+ available admin choices for this object. Use this
+ with ``meta.LazyDate`` to limit choices of objects
+ by date. For example::
+
limit_choices_to = {'pub_date__lte' : meta.LazyDate()}
-
+
only allows the choice of related objects with a
``pub_date`` before the current date/time to be
chosen.
-
+
Not compatible with ``edit_inline``.
-
+
``max_num_in_admin`` For inline-edited objects, this is the maximum
number of related objects to display in the admin.
- Thus, if a pizza could only have up to 10
+ Thus, if a pizza could only have up to 10
toppings, ``max_num_in_admin=10`` would ensure
that a user never enters more than 10 toppings.
-
+
Note that this doesn't ensure more than 10 related
- toppings ever get created.
-
+ toppings ever get created. It just controls the
+ interface.
+
``min_num_in_admin`` The minimum number of related objects displayed in
- the admin. Normally, at the creation stage
+ the admin. Normally, at the creation stage,
``num_in_admin`` inline objects are shown, and at
- the edit stage ``num_extra_on_change`` objects are
- shown in addition to all pre-existing related
- objects. However, no fewer than
+ the edit stage ``num_extra_on_change`` blank
+ objects are shown in addition to all pre-existing
+ related objects. However, no fewer than
``min_num_in_admin`` related objects will ever be
displayed.
-
- ``num_extra_on_change`` The number of extra blank related object fields to
+
+ ``num_extra_on_change`` The number of extra blank related-object fields to
show at the change stage.
-
+
``num_in_admin`` The default number of inline objects to display
on the object page at the add stage.
-
+
``raw_id_admin`` Only display a field for the integer to be entered
- instead of a drop-down menu. This is useful when
+ instead of a drop-down menu. This is useful when
related to an object type that will have too many
- rows to make a menu practical.
-
+ rows to make a select box practical.
+
Not used with ``edit_inline``.
-
- ``rel_name`` The name of the relation. In the above example,
- this would default to 'pizza' (so that the
+
+ ``rel_name`` The name of the relation. In the above example,
+ this would default to 'pizza' (so that the
``Toppings`` object would have a ``get_pizza()``
- function; if you set ``rel_name`` to "pie", then
+ function. If you set ``rel_name`` to "pie", then
the function would be called ``get_pie()`` and the
field name would be ``pie_id``.
-
+
``related_name`` The name to use for the relation from the related
object back to this one. For example, when if
``Topping`` has this field::
-
+
meta.ForeignKey(Pizza)
-
+
the ``related_name`` will be "topping" (taken from
the class name which will in turn give ``Pizza``
- methods like ``get_topping_list()`` and
- ``get_topping_count()``.
-
+ methods like ``get_topping_list()`` and
+ ``get_topping_count()``.
+
If you instead were to use::
-
+
meta.ForeignKey(Pizza, related_name="munchie")
-
+
then the methods would be called
``get_munchie_list()``, ``get_munchie_count()``,
etc.
-
+
This is only really useful when you have a single
object that relates to the same object more than
once. For example, if a ``Story`` object has both
- ``primary_category`` and ``secondary_category``
+ ``primary_category`` and ``secondary_category``
fields, to make sure that the category objects
have the correct methods, you'd use fields like::
-
+
...
meta.ForeignKey(Category, name="primary_category_id",
rel_name="primary_category",
related_name="primary_story"),
-
+
meta.ForeignKey(Category, name="secondary_category_id",
rel_name="secondary_category",
related_name="secondary_story"),
...
-
- which would give the category objects methods
- named ``get_primary_story_list()`` and
+
+ which would give the category objects methods
+ named ``get_primary_story_list()`` and
``get_secondary_story_list()``.
-
+
``to_field`` The field on the related object that the relation
- is to. This is almost always ``id``, but if the
- PK on the other object is named something
+ is to. This is almost always ``id``, but if the
+ primary key on the other object is named something
different, this is how to indicate that.
======================= ============================================================
-.. _`Database API reference`: http://www.djangoproject.com/documentation/db_api/
-
+.. _`Database API reference`: http://www.djangoproject.com/documentation/db_api/
+
``ImageField``
- Like a ``FieldField``, but validates that the uploaded object is a valid
- image. Has two extra optional arguments, ``height_field`` and ``width_field``
+ Like a ``FieldField``, but validates that the uploaded object is a valid
+ image. Has two extra optional arguments, ``height_field`` and ``width_field``
which, if set, will be auto-populated with the height and width of the image.
-
+
+ Requires the `Python Imaging Library`_.
+
+ .. _Python Imaging Library: http://www.pythonware.com/products/pil/
+
``IntegerField``
- An integer, surprisingly.
-
+ An integer.
+
``IPAddressField``
An IP address, in string format (i.e. "24.124.1.30").
-
+
``ManyToManyField``
A many-to-many relation to another object. For example (taken from the
``core.flatfiles`` object::
-
+
class FlatFile(meta.Model):
fields = (
...
meta.ManyToManyField(Site),
)
-
+
Many-to-many relations are a bit different from other fields. First, they
- aren't actually a field per se since they use a intermediary join table.
- Second, they don't take any of the same options as the rest of the fields,
- the only options taken are:
-
+ aren't actually a field per se, because they use a intermediary join table.
+ Second, they don't take any of the same options as the rest of the fields.
+ The only options taken are:
+
======================= ============================================================
Option Description
======================= ============================================================
- ``related_name`` See the description of ``related_name`` in
+ ``related_name`` See the description of ``related_name`` in
``ManyToOneField``, above.
-
- ``filter_interface`` Use a nifty unobtrusive Javascript "filter" interface
- instead of the usability-challenged ``<select multiple>``.
- The value should be ``meta.HORIZONTAL`` or ``meta.VERTICAL``
- (i.e. should the interface be stacked horizontally or
+
+ ``filter_interface`` Use a nifty unobtrusive Javascript "filter" interface
+ instead of the usability-challenged ``<select multiple>``
+ in the admin form for this object. The value should be
+ ``meta.HORIZONTAL`` or ``meta.VERTICAL`` (i.e.
+ should the interface be stacked horizontally or
vertically).
-
+
``limit_choices_to`` See the description under ``ManyToOneField``, above.
======================= ============================================================
``NullBooleanField``
Like a ``BooleanField``, but allows ``NULL`` as one of the options. Use this
- instead of a ``BooleanField`` with ``null=True`` .
-
+ instead of a ``BooleanField`` with ``null=True``.
+
``OneToOneField``
Signifies a one-to-one relationship. This is most useful on the primary key
- of an object when that object "extends" another object in some way.
-
+ of an object when that object "extends" another object in some way.
+
For example, if you are building a database of "places", you would build pretty
standard stuff like address, phone number, etc. in the database. If you then
wanted to build a database of restaurants on top of the places, instead of
@@ -474,237 +481,246 @@ Field Types
a restaurant "is-a" place). This ``OneToOneField`` will actually replace
the primary key ``id`` field (since one-to-one relations share the same
primary key), and has a few in the admin interface:
-
+
* No selection interface is displayed on ``Restaurant`` pages; there will
be one (and only one) ``Restaurant`` for each place.
-
+
* On the ``Restaurant`` change list, every single ``Place`` -- weather it
- has an associated ``Restaurant`` or not -- will be displayed. Adding
+ has an associated ``Restaurant`` or not -- will be displayed. Adding
a ``Restaurant`` to a ``Place`` just means filling out the required
``Restaurant`` fields.
``PhoneNumberField``
Validates that the value is a valid phone number.
-
+
``PositiveIntegerField``
Like an ``IntegerField``, but must be positive.
-
+
``PositiveSmallIntegerField``
- Like a ``PositiveIntegerField``, but only allows values below 32767.
-
+ Like a ``PositiveIntegerField``, but only allows values under a certain
+ (database-dependent) point.
+
``SlugField``
- A "slug" suitable for parts of a URL; only allows alpha-numeric characters and
- underscores.
-
+ A "slug," suitable for parts of a URL. Only allows alphanumeric characters
+ and underscores.
+
Implies ``maxlength=50`` and ``db_index=True``.
-
- Accepts an extra option, ``prepopulate_from`` which is a list of fields from
- which to auto-populate the slug.
-
+
+ Accepts an extra option, ``prepopulate_from``, which is a list of fields
+ from which to auto-populate the slug, via JavaScript, in the object's admin
+ form.
+
``SmallIntegerField``
- Like an ``IntegerField``, but must be between -32768 and 32767.
-
+ Like an ``IntegerField``, but only allows values under a certain
+ (database-dependent) point.
+
``TextField``
A large text field (``<textarea>`` in HTML).
-
+
``TimeField``
- A time. Accepts the same auto-population options as ``DateField`` and
+ A time. Accepts the same auto-population options as ``DateField`` and
``DateTimeField``.
-
+
``URLField``
- A field for a URL. If the ``verify_exists`` option is ``True``, the URL given
- will be checked for existence (i.e. actually loads and doesn't give a 404
- response).
-
+ A field for a URL. If the ``verify_exists`` option is ``True`` (default),
+ the URL given will be checked for existence (i.e., the URL actually loads
+ and doesn't give a 404 response).
+
``USStateField``
- A US state.
-
+ A two-letter U.S. state abbreviation.
+
``XMLField``
- A field containing XML. Takes one required argument, ``schema_path`` which
- is the path to a RelaxNG_ scheme against which to validate the field.
-
+ A field containing XML. Takes one required argument, ``schema_path``, which
+ is the filesystem path to a RelaxNG_ schema against which to validate the
+ field.
+
.. _RelaxNG: http://www.relaxng.org/
Admin options
=============
The ``admin`` field in the model tells Django how to construct the admin
-interface for the object. The field is an instance of the ``meta.Admin``
+interface for the object. The field is an instance of the ``meta.Admin``
object, which has the following options (of which only ``fields`` is required):
-``date_hierarchy``
+``date_hierarchy``
To allow filtering of objects in the admin by date, set ``date_hierarchy``
to the name of the field to filter by::
-
+
date_hierarchy = 'order_date'
-
+
``fields``
A list of fieldsets to display on the admin page. Each fieldset is a 2-tuple:
``(name, field_options)``. The ``name`` is a string to name the field set,
- and ``field_options`` is a dictionary of information about the fields to be
- displayed in that fieldset. This dictionary has the following keys:
-
+ and ``field_options`` is a dictionary of information about the fields to be
+ displayed in that fieldset. This dictionary has the following keys:
+
``fields``
- A tuple of field names to display in this fieldset. To display
+ A tuple of field names to display in this fieldset. To display
multiple fields on the same line, wrap those fields in their
own tuple.
-
+
This key is required in the dict.
-
+
``classes``
- Extra CSS classes to apply to the fieldset. This is a simple
- string; you can apply multiple classes by separating them with
+ Extra CSS classes to apply to the fieldset. This is a simple
+ string. You can apply multiple classes by separating them with
spaces.
-
- Two useful classes defined by the default stylesheet are ``collapse``
- and ``wide``. Fieldsets with the ``collapse`` style will be
- initially collapsed in the admin and replaced with a small "click
- to expand" link. Fieldsets with the ``wide`` style will be given
- extra horizontal space.
-
+
+ Two useful classes defined by the default stylesheet are
+ ``collapse`` and ``wide``. Fieldsets with the ``collapse`` style
+ will be initially collapsed in the admin and replaced with a small
+ "click to expand" link. Fieldsets with the ``wide`` style will be
+ given extra horizontal space.
+
For example (taken from the ``core.flatfiles`` model)::
-
+
fields = (
(None, {
'fields': ('url', 'title', 'content', 'sites')
}),
('Advanced options', {
- 'classes': 'collapse',
+ 'classes': 'collapse',
'fields' : ('enable_comments', 'registration_required', 'template_name')
}),
),
-
+
results in an admin that looks like:
-
+
.. image:: http://media.djangoproject.com/img/doc/flatfiles_admin.png
-
+
``js``
- Extra JavaScript files to link into the admin screen. This can be used to
- tweak a given type of admin page in JS or to provide "quick links" to fill
- in default values for certain fields.
-
+ A list of strings representing URLs of JavaScript files to link into the
+ admin screen. This can be used to tweak a given type of admin page in JS or
+ to provide "quick links" to fill in default values for certain fields.
+
``list_display``
List of fields to display on the list page in the admin.
-
+
There are a few special cases that do other things besides displaying the
contents of the given fields:
-
- * If the field given has a relationship, that relationship is
+
+ * If the field given has a relationship, that relationship is
followed and the ``repr()`` of the related object is displayed.
-
+
* If the field is a ``BooleanField``, a "on" or "off" icon will
be displayed instead of ``True`` or ``False``.
-
- * If the field name given does not exist, a function of the model
- will be searched for and called if present. This function
- should have a ``short_description`` attribute that will be
- used as the header for the field.
-
- See the exmaple below.
-
+
+ * If the field name is a method of the model, it'll be called, and the
+ output will be displayed. This method should have a
+ ``short_description`` function attribute, for use as the header for
+ the field.
+
+ See the example below.
+
``list_filter``
- List of fields to filter by. Each field should either be a ``BooleanField``
+ List of fields to filter by. Each field should either be a ``BooleanField``
or else a field with a ``ManyToOne`` relation.
-
- An example of how ``list_display`` and ``list_filter`` work (taken from
- the ``auth.user`` model)::
-
+
+ Here's an example of how ``list_display`` and ``list_filter`` work (taken
+ from the ``auth.user`` model)::
+
list_display = ('username', 'email', 'first_name', 'last_name', 'is_staff'),
list_filter = ('is_staff', 'is_superuser'),
-
- results in a admin that looks like:
-
+
+ This results in a admin that looks like:
+
.. image:: http://media.djangoproject.com/img/doc/users_changelist.png
-
+
(This example also has ``search_fields`` defined; see below).
-
+
``ordering``
An ordering tuple (see the `Options for models`_, above) that gives a
- different ordering for the admin change list. If not given, the model's
- default ordering will be used.
-
+ different ordering for the admin change list. If this isn't given, the
+ model's default ordering will be used.
+
``save_as``
Enables a "save as" feature on object pages. Normally, objects have three
save options: "Save", "Save and continue editing", and "Save and add
- another". If ``save_as`` is ``True``, "Save and add another" will be
+ another". If ``save_as`` is ``True``, "Save and add another" will be
replaced by a "Save as" button.
-
+
+ "Save as" means the object will be saved as a new object (with a new ID),
+ rather than the old object.
+
``save_on_top``
If this option is ``True``, object pages will have the save buttons across
the top as well as at the bottom of the page.
-
+
``search_fields``
- A list of fields to provide a text search for. These fields should,
- obviously, be some kind of text field.
-
+ A list of field names to provide a text search for. These fields should,
+ obviously, be some kind of text field, such as ``CharField`` or
+ ``TextField``.
+
Model methods
=============
There are a number of methods you can define on model objects to control the
object's behavior. First, any methods you define will be available as methods
-of object instances. For example::
+of object instances. For example::
class Pizza(meta.Model):
fields = (
...
- )
-
+ )
+
def is_disgusting(self):
- return "anchovices" in [topping.name for topping in self.get_topping_list()]
-
-Now, every ``Pizza`` object will have a ``is_disgusting()`` method.
+ return "anchovies" in [topping.name for topping in self.get_topping_list()]
+
+Now, every ``Pizza`` object will have a ``is_disgusting()`` method.
There are a few object methods that have special meaning:
``__repr__``
- Django uses ``repr(obj)`` in a number of places, the most notable as the
- value inserted into a template when it displays an object. Thus, you should
+ Django uses ``repr(obj)`` in a number of places, most notably as the value
+ inserted into a template when it displays an object. Thus, you should
return a nice, human-readable string for the object's ``__repr__``.
-
+
``get_absolute_url``
- If an object defines a ``get_absolute_url`` method, it is used to
- associate a URL with an object. For example:
-
+ If an object defines a ``get_absolute_url`` method, it is used to
+ associate a URL with an object. For example:
+
def get_absolute_url(self):
return "/pizzas/%i/" % self.id
-
- The most useful place this is used is in the admin interface; if an object
- defines ``get_absolute_url`` then the object detail page will have a "View
- on site" link that will jump you directly to the object's public view.
-
+
+ The most useful place this is used is in the admin interface. If an object
+ defines ``get_absolute_url``, the object detail page will have a "View on
+ site" link that will jump you directly to the object's public view.
+
``_pre_save``
- This method will be called just before the object is saved into the
- database; you can use it to (for example) calculate aggregate values from
- other fields before the object is saved.
-
+ This method is called just before an object is saved to the database. For
+ example, you can use it to calculate aggregate values from other fields
+ before the object is saved.
+
``_post_save``
- Called just after the object is saved to the database. This could be used
- to update other tables, update cached information, etc.
-
+ This method is called just after the object is saved to the database. This
+ could be used to update other tables, update cached information, etc.
+
Module-level methods
--------------------
-Since each data class in effect turns into a module, there are times you'll want
-to write methods that live in that module. Any model method that begins with
-"_module_" is turned into a module-level method::
+Since each data class effectively turns into a "magic" Python module under
+``django.models``, there are times you'll want to write methods that live in
+that module. Any model method that begins with "_module_" is turned into a
+module-level function::
class Pizza(meta.Model):
fields = (
...
)
-
+
def _module_get_pizzas_to_deliver():
return get_list(delivered__exact=False)
-
+
This will make the top-level ``pizzas`` module have a ``get_pizzas_to_deliver()``
method::
>>> from django.models.pizza_hut import pizzas
>>> pizzas.get_pizzas_to_deliver()
[ ... ]
-
-Note that the scope of these methods is modified to be the same has the module
-scope (so that's how the raw ``get_list`` works).
+
+Note that the scope of these methods is modified to be the same as the module
+scope.
Manipulator methods
-------------------
@@ -712,20 +728,17 @@ Manipulator methods
Similarly, you can add methods to the object's manipulators (see the formfields
documentation for more on manipulators) by defining methods that being with
"_manipulator_". This is most useful for providing custom validators for certain
-fields since manipulators automatically call any method that begins with
+fields because manipulators automatically call any method that begins with
"validate"::
class Pizza(meta.Model):
fields = (
...
)
-
+
def _manipulator_validate_customer_id(self, field_data, all_data):
from django.core import validators
from django.conf.settings import BAD_CUSTOMER_IDS
-
+
if int(field_data) in BAD_CUSTOMER_IDS:
raise validators.ValidationError("We don't deliver to this customer")
-
-
-
Please sign in to comment.
Something went wrong with that request. Please try again.