p31829507
/
django
mirror of https://github.com/django/django.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Fixed #18637 - Updated some documentation for aspects of models that are ModelForm specific, not admin specific. 

Thanks Ben Sturmfels for the patch.
This commit is contained in:
Tim Graham 2012-08-21 16:29:16 -04:00
parent 3fd89d9903
commit 13d47c3f33
2 changed files with 58 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

90
docs/ref/models/fields.txt
View File

@ -70,8 +70,8 @@ If ``True``, the field is allowed to be blank. Default is ``False``.
Note that this is different than :attr:`~Field.null`. :attr:`~Field.null` is
purely database-related, whereas :attr:`~Field.blank` is validation-related. If
a field has ``blank=True``, validation on Django's admin site will allow entry
of an empty value. If a field has ``blank=False``, the field will be required.
a field has ``blank=True``, form validation will allow entry of an empty value.
If a field has ``blank=False``, the field will be required.
.. _field-choices:
@ -81,14 +81,11 @@ of an empty value. If a field has ``blank=False``, the field will be required.
.. attribute:: Field.choices
An iterable (e.g., a list or tuple) of 2-tuples to use as choices for this
field.
field. If this is given, the default form widget will be a select box with
these choices instead of the standard text 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 is an iterable of 2-tuples; the first element in each
tuple is the actual value to be stored, and the second element is the
human-readable name. For example::
The first element in each tuple is the actual value to be stored, and the
second element is the human-readable name. For example::
YEAR_IN_SCHOOL_CHOICES = (
('FR', 'Freshman'),
@ -203,8 +200,8 @@ callable it will be called every time a new object is created.
.. attribute:: Field.editable
If ``False``, the field will not be editable in the admin or via forms
automatically generated from the model class. Default is ``True``.
If ``False``, the field will not be displayed in the admin or any other
:class:`~django.forms.ModelForm`. Default is ``True``.
``error_messages``
------------------
@ -224,11 +221,11 @@ the `Field types`_ section below.
.. attribute:: Field.help_text
Extra "help" text to be displayed under the field on the object's admin form.
It's useful for documentation even if your object doesn't have an admin form.
Extra "help" text to be displayed with the form widget. It's useful for
documentation even if your field isn't used on a form.
Note that this value is *not* HTML-escaped when it's displayed in the admin
interface. This lets you include HTML in :attr:`~Field.help_text` if you so
Note that this value is *not* HTML-escaped in automatically-generated
forms. This lets you include HTML in :attr:`~Field.help_text` if you so
desire. For example::
help_text="Please use the following format: <em>YYYY-MM-DD</em>."
@ -259,7 +256,7 @@ Only one primary key is allowed on an object.
If ``True``, this field must be unique throughout the table.
This is enforced at the database level and at the Django admin-form level. If
This is enforced at the database level and by model validation. If
you try to save a model with a duplicate value in a :attr:`~Field.unique`
field, a :exc:`django.db.IntegrityError` will be raised by the model's
:meth:`~django.db.models.Model.save` method.
@ -279,7 +276,7 @@ For example, if you have a field ``title`` that has
``unique_for_date="pub_date"``, then Django wouldn't allow the entry of two
records with the same ``title`` and ``pub_date``.
This is enforced at the Django admin-form level but not at the database level.
This is enforced by model validation but not at the database level.
``unique_for_month``
--------------------
@ -337,7 +334,7 @@ otherwise. See :ref:`automatic-primary-key-fields`.
A 64 bit integer, much like an :class:`IntegerField` except that it is
guaranteed to fit numbers from -9223372036854775808 to 9223372036854775807. The
admin represents this as an ``<input type="text">`` (a single-line input).
default form widget for this field is a :class:`~django.forms.TextInput`.
``BooleanField``
@ -347,7 +344,8 @@ admin represents this as an ``<input type="text">`` (a single-line input).
A true/false field.
The admin represents this as a checkbox.
The default form widget for this field is a
:class:`~django.forms.CheckboxInput`.
If you need to accept :attr:`~Field.null` values then use
:class:`NullBooleanField` instead.
@ -361,7 +359,7 @@ A string field, for small- to large-sized strings.
For large amounts of text, use :class:`~django.db.models.TextField`.
The admin represents this as an ``<input type="text">`` (a single-line input).
The default form widget for this field is a :class:`~django.forms.TextInput`.
:class:`CharField` has one extra required argument:
@ -414,9 +412,10 @@ optional arguments:
for creation of timestamps. Note that the current date is *always* used;
it's not just a default value that you can override.
The admin represents this as an ``<input type="text">`` with a JavaScript
calendar, and a shortcut for "Today". Includes an additional ``invalid_date``
error message key.
The default form widget for this field is a
:class:`~django.forms.TextInput`. The admin adds a JavaScript calendar,
and a shortcut for "Today". Includes an additional ``invalid_date`` error
message key.
.. note::
As currently implemented, setting ``auto_now`` or ``auto_now_add`` to
@ -431,8 +430,9 @@ error message key.
A date and time, represented in Python by a ``datetime.datetime`` instance.
Takes the same extra arguments as :class:`DateField`.
The admin represents this as two ``<input type="text">`` fields, with
JavaScript shortcuts.
The default form widget for this field is a single
:class:`~django.forms.TextInput`. The admin uses two separate
:class:`~django.forms.TextInput` widgets with JavaScript shortcuts.
``DecimalField``
----------------
@ -461,7 +461,7 @@ decimal places::
models.DecimalField(..., max_digits=19, decimal_places=10)
The admin represents this as an ``<input type="text">`` (a single-line input).
The default form widget for this field is a :class:`~django.forms.TextInput`.
.. note::
@ -539,8 +539,8 @@ Also has one optional argument:
Optional. A storage object, which handles the storage and retrieval of your
files. See :doc:`/topics/files` for details on how to provide this object.
The admin represents this field as an ``<input type="file">`` (a file-upload
widget).
The default form widget for this field is a
:class:`~django.forms.widgets.FileInput`.
Using a :class:`FileField` or an :class:`ImageField` (see below) in a model
takes a few steps:
@ -725,7 +725,7 @@ can change the maximum length using the :attr:`~CharField.max_length` argument.
A floating-point number represented in Python by a ``float`` instance.
The admin represents this as an ``<input type="text">`` (a single-line input).
The default form widget for this field is a :class:`~django.forms.TextInput`.
.. _floatfield_vs_decimalfield:
@ -776,16 +776,16 @@ length using the :attr:`~CharField.max_length` argument.
.. class:: IntegerField([**options])
An integer. The admin represents this as an ``<input type="text">`` (a
single-line input).
An integer. The default form widget for this field is a
:class:`~django.forms.TextInput`.
``IPAddressField``
------------------
.. class:: IPAddressField([**options])
An IP address, in string format (e.g. "192.0.2.30"). The admin represents this
as an ``<input type="text">`` (a single-line input).
An IP address, in string format (e.g. "192.0.2.30"). The default form widget
for this field is a :class:`~django.forms.TextInput`.
``GenericIPAddressField``
-------------------------
@ -795,8 +795,8 @@ as an ``<input type="text">`` (a single-line input).
.. versionadded:: 1.4
An IPv4 or IPv6 address, in string format (e.g. ``192.0.2.30`` or
``2a02:42fe::4``). The admin represents this as an ``<input type="text">``
(a single-line input).
``2a02:42fe::4``). The default form widget for this field is a
:class:`~django.forms.TextInput`.
The IPv6 address normalization follows :rfc:`4291#section-2.2` section 2.2,
including using the IPv4 format suggested in paragraph 3 of that section, like
@ -823,8 +823,8 @@ are converted to lowercase.
.. class:: NullBooleanField([**options])
Like a :class:`BooleanField`, but allows ``NULL`` as one of the options. Use
this instead of a :class:`BooleanField` with ``null=True``. The admin represents
this as a ``<select>`` box with "Unknown", "Yes" and "No" choices.
this instead of a :class:`BooleanField` with ``null=True``. The default form
widget for this field is a :class:`~django.forms.NullBooleanSelect`.
``PositiveIntegerField``
------------------------
@ -875,8 +875,8 @@ Like an :class:`IntegerField`, but only allows values under a certain
.. class:: TextField([**options])
A large text field. The admin represents this as a ``<textarea>`` (a multi-line
input).
A large text field. The default form widget for this field is a
:class:`~django.forms.Textarea`.
.. admonition:: MySQL users
@ -893,8 +893,8 @@ input).
A time, represented in Python by a ``datetime.time`` instance. Accepts the same
auto-population options as :class:`DateField`.
The admin represents this as an ``<input type="text">`` with some JavaScript
shortcuts.
The default form widget for this field is a :class:`~django.forms.TextInput`.
The admin adds some JavaScript shortcuts.
``URLField``
------------
@ -903,7 +903,7 @@ shortcuts.
A :class:`CharField` for a URL.
The admin represents this as an ``<input type="text">`` (a single-line input).
The default form widget for this field is a :class:`~django.forms.TextInput`.
Like all :class:`CharField` subclasses, :class:`URLField` takes the optional
:attr:`~CharField.max_length`argument. If you don't specify
@ -979,9 +979,9 @@ define the details of how the relation works.
.. attribute:: ForeignKey.limit_choices_to
A dictionary of lookup arguments and values (see :doc:`/topics/db/queries`)
that limit the available admin choices for this object. Use this with
functions from the Python ``datetime`` module to limit choices of objects by
date. For example::
that limit the available admin or ModelForm choices for this object. Use
this with functions from the Python ``datetime`` module to limit choices of
objects by date. For example::
limit_choices_to = {'pub_date__lte': datetime.now}

28
docs/topics/db/models.txt
View File

@ -108,8 +108,8 @@ determine a few things:
* The database column type (e.g. ``INTEGER``, ``VARCHAR``).
* The :doc:`widget </ref/forms/widgets>` to use in Django's admin interface,
if you care to use it (e.g. ``<input type="text">``, ``<select>``).
* The default :doc:`widget </ref/forms/widgets>` to use when rendering a form
field (e.g. ``<input type="text">``, ``<select>``).
* The minimal validation requirements, used in Django's admin and in
automatically-generated forms.
@ -143,13 +143,13 @@ ones:
Note that this is different than :attr:`~Field.null`.
:attr:`~Field.null` is purely database-related, whereas
:attr:`~Field.blank` is validation-related. If a field has
:attr:`blank=True <Field.blank>`, validation on Django's admin site will
:attr:`blank=True <Field.blank>`, form validation will
allow entry of an empty value. If a field has :attr:`blank=False
<Field.blank>`, the field will be required.
:attr:`~Field.choices`
An iterable (e.g., a list or tuple) of 2-tuples to use as choices for
this field. If this is given, Django's admin will use a select box
this field. If this is given, the default form widget will be a select box
instead of the standard text field and will limit choices to the choices
given.
@ -164,7 +164,7 @@ ones:
)
The first element in each tuple is the value that will be stored in the
database, the second element will be displayed by the admin interface,
database, the second element will be displayed by the default form widget
or in a ModelChoiceField. Given an instance of a model object, the
display value for a choices field can be accessed using the
``get_FOO_display`` method. For example::
@ -195,9 +195,8 @@ ones:
created.
:attr:`~Field.help_text`
Extra "help" text to be displayed under the field on the object's admin
form. It's useful for documentation even if your object doesn't have an
admin form.
Extra "help" text to be displayed with the form widget. It's useful for
documentation even if your field isn't used on a form.
:attr:`~Field.primary_key`
If ``True``, this field is the primary key for the model.
@ -360,13 +359,12 @@ It doesn't matter which model has the
:class:`~django.db.models.ManyToManyField`, but you should only put it in one
of the models -- not both.
Generally, :class:`~django.db.models.ManyToManyField` instances should go in the
object that's going to be edited in the admin interface, if you're using
Django's admin. In the above example, ``toppings`` is in ``Pizza`` (rather than
``Topping`` having a ``pizzas`` :class:`~django.db.models.ManyToManyField` )
because it's more natural to think about a pizza having toppings than a
topping being on multiple pizzas. The way it's set up above, the ``Pizza`` admin
form would let users select the toppings.
Generally, :class:`~django.db.models.ManyToManyField` instances should go in
the object that's going to be edited on a form. In the above example,
``toppings`` is in ``Pizza`` (rather than ``Topping`` having a ``pizzas``
:class:`~django.db.models.ManyToManyField` ) because it's more natural to think
about a pizza having toppings than a topping being on multiple pizzas. The way
it's set up above, the ``Pizza`` form would let users select the toppings.
.. seealso::