mirror of
https://github.com/django/django.git
synced 2025-06-08 21:19:13 +00:00
Further edits to page structure & fixed CI errors.
This commit is contained in:
parent
e5cc6a6ae6
commit
14b4149216
@ -1,25 +1,25 @@
|
|||||||
================================================
|
===========
|
||||||
ModelForm ``Meta`` Options and Factory Functions
|
ModelForms
|
||||||
================================================
|
===========
|
||||||
|
|
||||||
.. module:: django.forms.models
|
.. module:: django.forms.models
|
||||||
:synopsis: ModelForm API reference for inner ``Meta`` class and factory
|
:synopsis: ModelForm API reference for inner ``Meta`` class and factory
|
||||||
functions
|
functions
|
||||||
|
|
||||||
.. admonition:: Other ModelForm-related documentation
|
.. class:: ModelForm
|
||||||
|
|
||||||
This document is an API reference for the :class:`~django.forms.ModelForm`
|
.. _ref-modelform:
|
||||||
class. For examples or additional context, please refer to the
|
|
||||||
documentation topic :doc:`Creating forms from models
|
.. currentmodule:: django.forms
|
||||||
</topics/forms/modelforms>`.
|
|
||||||
|
:class:`~django.forms.ModelForm` API reference. For introductory material about
|
||||||
|
ModelForms, see the :doc:`/topics/forms/modelforms` topic guide.
|
||||||
|
|
||||||
.. _ref-modelform-meta-options:
|
.. _ref-modelform-meta-options:
|
||||||
|
|
||||||
ModelForm ``Meta`` Options
|
ModelForm ``Meta`` Options
|
||||||
==========================
|
==========================
|
||||||
|
|
||||||
.. currentmodule:: django.forms
|
|
||||||
|
|
||||||
The :class:`~django.forms.ModelForm` helper class can be used to build forms
|
The :class:`~django.forms.ModelForm` helper class can be used to build forms
|
||||||
that closely reflect specific Django models. The exact structure of the form
|
that closely reflect specific Django models. The exact structure of the form
|
||||||
produced can be controlled by setting metadata options as attributes of an inner
|
produced can be controlled by setting metadata options as attributes of an inner
|
||||||
@ -32,13 +32,14 @@ produced can be controlled by setting metadata options as attributes of an inner
|
|||||||
from django.forms import ModelForm
|
from django.forms import ModelForm
|
||||||
from myLibraryApp.models import Book
|
from myLibraryApp.models import Book
|
||||||
|
|
||||||
class BookForm(ModelForm)
|
|
||||||
|
class BookForm(ModelForm):
|
||||||
class Meta:
|
class Meta:
|
||||||
model = Book
|
model = Book
|
||||||
fields = [ 'title', 'author' ]
|
fields = ["title", "author"]
|
||||||
help_texts = {
|
help_texts = {
|
||||||
'title' : 'The title of the book',
|
"title": "The title of the book",
|
||||||
'author': 'The author of the book'
|
"author": "The author of the book",
|
||||||
}
|
}
|
||||||
# ... other attributes
|
# ... other attributes
|
||||||
|
|
||||||
@ -51,61 +52,39 @@ produced can be controlled by setting metadata options as attributes of an inner
|
|||||||
themselves, raise an error (though they might cause another error to be
|
themselves, raise an error (though they might cause another error to be
|
||||||
raised if they affect a required attribute).
|
raised if they affect a required attribute).
|
||||||
|
|
||||||
It is **not** necessary for every option to be set for each ``Meta`` class,
|
Other than :attr:`~ModelFormOptions.model` and at least one of
|
||||||
though some (indicated below) are required.
|
:attr:`~ModelFormOptions.fields` and :attr:`~ModelFormOptions.exclude`, ``Meta``
|
||||||
|
attributes are optional. It is **not** necessary for every option to be set for
|
||||||
|
each ``Meta`` class, nor does every included field need to be included in every
|
||||||
|
option used. If an option isn't set, or if a model's field isn't used with a
|
||||||
|
particular option, Django will fall back on whatever has already been defined
|
||||||
|
for a field in their model or whatever defaults might exist for that field's
|
||||||
|
type.
|
||||||
|
|
||||||
In most cases, if an option isn't set, or if a model's field isn't used with a
|
Optional ``Meta`` attributes, other than
|
||||||
particular option, Django will fallback on whatever has already been defined for
|
:attr:`~ModelFormOptions.localized_fields` and
|
||||||
a field in their model or whatever defaults might exist for that field's type.
|
:attr:`~ModelFormOptions.formfield_callback`, expect a dictionary that maps a
|
||||||
|
model field name string to some other object or string. Including invalid or
|
||||||
|
excluded field name strings in these dictionaries is possible but should have no
|
||||||
|
effect since fields that haven't been included would never be accessed.
|
||||||
|
|
||||||
.. _ref-modelform-meta-required:
|
``error_messages``
|
||||||
|
------------------
|
||||||
|
|
||||||
Required ``Meta`` Options
|
.. attribute:: ModelFormOptions.error_messages
|
||||||
----------------------------
|
|
||||||
|
|
||||||
``model``
|
Expects a dictionary that maps a model field name string to a dictionary of
|
||||||
~~~~~~~~~
|
error message keys (``null``, ``blank``, ``invalid``, ``unique``, etc.)
|
||||||
|
mapped to custom error messages.
|
||||||
|
|
||||||
.. attribute:: ModelFormOptions.model
|
Where a field doesn't have an error message dictionary mapped to it in
|
||||||
|
:attr:`~ModelFormOptions.error_messages`, Django will fall back on error
|
||||||
*Required.* A :class:`django.db.models.Model` to be used for this
|
messages defined in that model field's
|
||||||
:class:`~django.forms.ModelForm`. This is **not** a string.
|
:attr:`django.db.models.Field.error_messages` and then finally on the
|
||||||
|
default error messages for that field type.
|
||||||
If no class is specified, a :exc:`ValueError` exception will be raised.
|
|
||||||
|
|
||||||
``fields``
|
|
||||||
~~~~~~~~~~
|
|
||||||
|
|
||||||
.. attribute:: ModelFormOptions.fields
|
|
||||||
|
|
||||||
*One of* :attr:`~ModelFormOptions.fields` *and*
|
|
||||||
:attr:`~ModelFormOptions.exclude` *must be set.* Expects a tuple of string
|
|
||||||
or list of strings where each string is the name of a field from the model
|
|
||||||
set in :attr:`~ModelFormOptions.model` or, instead, the single, special
|
|
||||||
string ``'__all__'``. Every field named in :attr:`~ModelFormOptions.fields`
|
|
||||||
will be included in the output form. Non-editable fields cannot be included.
|
|
||||||
|
|
||||||
* If set to the special string ``'__all__'``, all non-editable model fields
|
|
||||||
will be included.
|
|
||||||
* Other than the special case of ``'__all__'``,
|
|
||||||
:attr:`~ModelFormOptions.fields` **cannot** be set to a single string,
|
|
||||||
even if only a single field is desired. The input for
|
|
||||||
:attr:`~ModelFormOptions.fields` must still be structured as a tuple of
|
|
||||||
strings (e.g., ``('myFieldName',)``) or list of strings (e.g., ``[
|
|
||||||
'myFieldName' ]``) or else a :exc:`TypeError` will be raised.
|
|
||||||
* If a string provided is not a valid field name for the model specified by
|
|
||||||
:attr:`ModelFormOptions.model` (e.g., the field doesn't exist on the model
|
|
||||||
or the field name contained a typo), a
|
|
||||||
:exc:`~django.core.exceptions.FieldError` exception will be raised.
|
|
||||||
* If a non-editable field name is provided, a
|
|
||||||
:exc:`~django.core.exceptions.FieldError` exception will be raised.
|
|
||||||
* If neither of :attr:`~ModelFormOptions.fields` or
|
|
||||||
:attr:`~ModelFormOptions.exclude` are set, an
|
|
||||||
:exc:`~django.core.exceptions.ImproperlyConfigured` exception will be
|
|
||||||
raised.
|
|
||||||
|
|
||||||
``exclude``
|
``exclude``
|
||||||
~~~~~~~~~~~
|
-----------
|
||||||
|
|
||||||
.. attribute:: ModelFormOptions.exclude
|
.. attribute:: ModelFormOptions.exclude
|
||||||
|
|
||||||
@ -127,43 +106,8 @@ Required ``Meta`` Options
|
|||||||
:class:`~django.core.exceptions.ImproperlyConfigured` exception will be
|
:class:`~django.core.exceptions.ImproperlyConfigured` exception will be
|
||||||
raised.
|
raised.
|
||||||
|
|
||||||
.. _ref-modelform-meta-optional:
|
|
||||||
|
|
||||||
Optional ``Meta`` Options
|
|
||||||
----------------------------
|
|
||||||
|
|
||||||
.. currentmodule:: django.forms
|
|
||||||
|
|
||||||
Additional ``Meta`` options can be set to define aspects of the included
|
|
||||||
model fields. All of these ``Meta`` attributes are optional and all, except for
|
|
||||||
:attr:`~ModelFormOptions.localized_fields` and
|
|
||||||
:attr:`~ModelFormOptions.formfield_callback`, expect a dictionary
|
|
||||||
that maps a model field name string to some other object or string. Including
|
|
||||||
invalid or excluded field name strings in these dictionaries is possible but
|
|
||||||
should have no effect since fields that haven't been included would never be
|
|
||||||
accessed.
|
|
||||||
|
|
||||||
When used, it isn't necessary for every included model field to appear in each
|
|
||||||
dictionary. Django has different fallback behaviors depending on which elements
|
|
||||||
have not been defined for a given included model field.
|
|
||||||
|
|
||||||
``error_messages``
|
|
||||||
~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
.. attribute:: ModelFormOptions.error_messages
|
|
||||||
|
|
||||||
Expects a dictionary that maps a model field name string to a dictionary of
|
|
||||||
error message keys (``null``, ``blank``, ``invalid``, ``unique``, etc.)
|
|
||||||
mapped to custom error messages.
|
|
||||||
|
|
||||||
Where a field doesn't have an error message dictionary mapped to it in
|
|
||||||
:attr:`~ModelFormOptions.error_messages`, Django will fall back on error
|
|
||||||
messages defined in that model field's
|
|
||||||
:attr:`django.db.models.Field.error_messages` and then finally on the
|
|
||||||
default error messages for that field type.
|
|
||||||
|
|
||||||
``field_classes``
|
``field_classes``
|
||||||
~~~~~~~~~~~~~~~~~
|
-----------------
|
||||||
|
|
||||||
.. attribute:: ModelFormOptions.field_classes
|
.. attribute:: ModelFormOptions.field_classes
|
||||||
|
|
||||||
@ -193,14 +137,43 @@ have not been defined for a given included model field.
|
|||||||
instead has :attr:`~django.forms.IntegerField.max_value`). In this case, a
|
instead has :attr:`~django.forms.IntegerField.max_value`). In this case, a
|
||||||
:exc:`TypeError` will be raised with the message:
|
:exc:`TypeError` will be raised with the message:
|
||||||
|
|
||||||
.. code-block:: pycon
|
.. code-block:: console
|
||||||
|
|
||||||
>>> TypeError: Field.__init__() got an unexpected keyword argument 'max_length'
|
>>> TypeError: Field.__init__() got an unexpected keyword argument 'max_length'
|
||||||
|
|
||||||
.. currentmodule:: django.forms
|
``fields``
|
||||||
|
----------
|
||||||
|
|
||||||
|
.. attribute:: ModelFormOptions.fields
|
||||||
|
|
||||||
|
*One of* :attr:`~ModelFormOptions.fields` *and*
|
||||||
|
:attr:`~ModelFormOptions.exclude` *must be set.* Expects a tuple of string
|
||||||
|
or list of strings where each string is the name of a field from the model
|
||||||
|
set in :attr:`~ModelFormOptions.model` or, instead, the single, special
|
||||||
|
string ``'__all__'``. Every field named in :attr:`~ModelFormOptions.fields`
|
||||||
|
will be included in the output form. Non-editable fields cannot be included.
|
||||||
|
|
||||||
|
* If set to the special string ``'__all__'``, all non-editable model fields
|
||||||
|
will be included.
|
||||||
|
* Other than the special case of ``'__all__'``,
|
||||||
|
:attr:`~ModelFormOptions.fields` **cannot** be set to a single string,
|
||||||
|
even if only a single field is desired. The input for
|
||||||
|
:attr:`~ModelFormOptions.fields` must still be structured as a tuple of
|
||||||
|
strings (e.g., ``('myFieldName',)``) or list of strings (e.g., ``[
|
||||||
|
'myFieldName' ]``) or else a :exc:`TypeError` will be raised.
|
||||||
|
* If a string provided is not a valid field name for the model specified by
|
||||||
|
:attr:`ModelFormOptions.model` (e.g., the field doesn't exist on the model
|
||||||
|
or the field name contained a typo), a
|
||||||
|
:exc:`~django.core.exceptions.FieldError` exception will be raised.
|
||||||
|
* If a non-editable field name is provided, a
|
||||||
|
:exc:`~django.core.exceptions.FieldError` exception will be raised.
|
||||||
|
* If neither of :attr:`~ModelFormOptions.fields` or
|
||||||
|
:attr:`~ModelFormOptions.exclude` are set, an
|
||||||
|
:exc:`~django.core.exceptions.ImproperlyConfigured` exception will be
|
||||||
|
raised.
|
||||||
|
|
||||||
``formfield_callback``
|
``formfield_callback``
|
||||||
~~~~~~~~~~~~~~~~~~~~~~
|
----------------------
|
||||||
|
|
||||||
.. attribute:: ModelFormOptions.formfield_callback
|
.. attribute:: ModelFormOptions.formfield_callback
|
||||||
|
|
||||||
@ -212,7 +185,7 @@ have not been defined for a given included model field.
|
|||||||
function, a :exc:`TypeError` will be raised.
|
function, a :exc:`TypeError` will be raised.
|
||||||
|
|
||||||
``help_texts``
|
``help_texts``
|
||||||
~~~~~~~~~~~~~~
|
--------------
|
||||||
|
|
||||||
.. attribute:: ModelFormOptions.help_texts
|
.. attribute:: ModelFormOptions.help_texts
|
||||||
|
|
||||||
@ -224,7 +197,7 @@ have not been defined for a given included model field.
|
|||||||
field's :attr:`~django.db.models.Field.help_text`.
|
field's :attr:`~django.db.models.Field.help_text`.
|
||||||
|
|
||||||
``labels``
|
``labels``
|
||||||
~~~~~~~~~~
|
----------
|
||||||
|
|
||||||
.. attribute:: ModelFormOptions.labels
|
.. attribute:: ModelFormOptions.labels
|
||||||
|
|
||||||
@ -236,7 +209,7 @@ have not been defined for a given included model field.
|
|||||||
attribute name.
|
attribute name.
|
||||||
|
|
||||||
``localized_fields``
|
``localized_fields``
|
||||||
~~~~~~~~~~~~~~~~~~~~
|
--------------------
|
||||||
|
|
||||||
.. attribute:: ModelFormOptions.localized_fields
|
.. attribute:: ModelFormOptions.localized_fields
|
||||||
|
|
||||||
@ -251,8 +224,18 @@ have not been defined for a given included model field.
|
|||||||
:attr:`~ModelFormOptions.localized_fields` can be set to the special string
|
:attr:`~ModelFormOptions.localized_fields` can be set to the special string
|
||||||
``'__all__'`` to include all fields.
|
``'__all__'`` to include all fields.
|
||||||
|
|
||||||
|
``model``
|
||||||
|
---------
|
||||||
|
|
||||||
|
.. attribute:: ModelFormOptions.model
|
||||||
|
|
||||||
|
*Required.* A :class:`django.db.models.Model` to be used for this
|
||||||
|
:class:`~django.forms.ModelForm`. This is **not** a string.
|
||||||
|
|
||||||
|
If no class is specified, a :exc:`ValueError` exception will be raised.
|
||||||
|
|
||||||
``widgets``
|
``widgets``
|
||||||
~~~~~~~~~~~
|
-----------
|
||||||
|
|
||||||
.. attribute:: ModelFormOptions.widgets
|
.. attribute:: ModelFormOptions.widgets
|
||||||
|
|
||||||
|
Loading…
x
Reference in New Issue
Block a user