Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

[1.4.x] Fixed #18637 - Updated some documentation for aspects of mode…

…ls that are ModelForm specific, not admin specific.

Thanks Ben Sturmfels for the patch.

Backport of 13d47c3 from master.
  • Loading branch information...
commit 27c2ccc1ea0d08752a480aae30d48be6126d21ff 1 parent 42aee6f
Tim Graham timgraham authored
Showing with 58 additions and 58 deletions.
  1. +45 −43 docs/ref/models/fields.txt
  2. +13 −15 docs/topics/db/models.txt
88 docs/ref/models/fields.txt
View
@@ -71,8 +71,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:
@@ -82,12 +82,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 looks like this::
+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 +202,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``
------------------
@@ -226,11 +225,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>."
@@ -261,7 +260,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.
@@ -281,7 +280,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``
--------------------
@@ -343,7 +342,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``
@@ -353,7 +352,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.
@@ -372,7 +372,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:
@@ -425,9 +425,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
@@ -442,8 +443,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``
----------------
@@ -472,7 +474,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::
@@ -541,8 +543,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:
@@ -710,7 +712,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:
@@ -761,16 +763,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``
-------------------------
@@ -780,8 +782,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
@@ -808,8 +810,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``
------------------------
@@ -860,8 +862,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
@@ -878,8 +880,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``
------------
@@ -902,7 +904,7 @@ A :class:`CharField` for a URL. Has one extra optional argument:
validating a URL being served by the same server will hang. This should not
be a problem for multithreaded servers.
-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
@@ -978,9 +980,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
@@ -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.
@@ -359,13 +358,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::
Please sign in to comment.
Something went wrong with that request. Please try again.