mirror of
https://github.com/django/django.git
synced 2025-09-04 19:35:05 +03:00
Fixed #35831 -- Documented the model form meta API in model form reference docs.
Co-authored-by: Jonathan <3218047+jernwerber@users.noreply.github.com> Co-authored-by: Mustafa <117516335+mspirbhai@users.noreply.github.com>
This commit is contained in:
Mustafa Pirbhai
Sarah Boyce
parent
eaaf01c96a
commit
183fcebf88
|
|
@ -1,15 +1,188 @@
|
|||
====================
|
||||
Model Form Functions
|
||||
====================
|
||||
|
||||
Model Form API reference. For introductory material about model forms, see the
|
||||
:doc:`/topics/forms/modelforms` topic guide.
|
||||
===========
|
||||
Model forms
|
||||
===========
|
||||
|
||||
.. module:: django.forms.models
|
||||
:synopsis: Django's functions for building model forms and formsets.
|
||||
:synopsis: ModelForm API reference for inner ``Meta`` class and factory
|
||||
functions
|
||||
|
||||
.. currentmodule:: django.forms
|
||||
|
||||
``ModelForm`` API reference. For introductory material about using a
|
||||
``ModelForm``, see the :doc:`/topics/forms/modelforms` topic guide.
|
||||
|
||||
Model form ``Meta`` API
|
||||
=======================
|
||||
|
||||
.. class:: ModelFormOptions
|
||||
|
||||
The ``_meta`` API is used to build forms that reflect a Django model. It is
|
||||
accessible through the ``_meta`` attribute of each model form, and is an
|
||||
``django.forms.models.ModelFormOptions`` instance.
|
||||
|
||||
The structure of the generated form can be customized by defining metadata
|
||||
options as attributes of an inner ``Meta`` class. For example::
|
||||
|
||||
from django.forms import ModelForm
|
||||
from myapp.models import Book
|
||||
|
||||
|
||||
class BookForm(ModelForm):
|
||||
class Meta:
|
||||
model = Book
|
||||
fields = ["title", "author"]
|
||||
help_texts = {
|
||||
"title": "The title of the book",
|
||||
"author": "The author of the book",
|
||||
}
|
||||
# ... other attributes
|
||||
|
||||
Required attributes are :attr:`~ModelFormOptions.model`, and either
|
||||
:attr:`~ModelFormOptions.fields` or :attr:`~ModelFormOptions.exclude`. All
|
||||
other ``Meta`` attributes are optional.
|
||||
|
||||
Optional attributes, other than :attr:`~ModelFormOptions.localized_fields` and
|
||||
:attr:`~ModelFormOptions.formfield_callback`, expect a dictionary that maps a
|
||||
model field name to a value. Any field that is not defined in the dictionary
|
||||
falls back to the field's default value.
|
||||
|
||||
.. admonition:: Invalid field names
|
||||
|
||||
Invalid or excluded field names in an optional dictionary attribute have no
|
||||
effect, since fields that are not included are not accessed.
|
||||
|
||||
.. admonition:: Invalid Meta class attributes
|
||||
|
||||
You may define any attribute on a ``Meta`` class. Typos or incorrect
|
||||
attribute names do not raise an error.
|
||||
|
||||
``error_messages``
|
||||
------------------
|
||||
|
||||
.. attribute:: ModelFormOptions.error_messages
|
||||
|
||||
A dictionary that maps a model field name to a dictionary of error message
|
||||
keys (``null``, ``blank``, ``invalid``, ``unique``, etc.) mapped to custom
|
||||
error messages.
|
||||
|
||||
When a field is not specified, Django will fall back on the 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.
|
||||
|
||||
``exclude``
|
||||
-----------
|
||||
|
||||
.. attribute:: ModelFormOptions.exclude
|
||||
|
||||
A tuple or list of :attr:`~ModelFormOptions.model` field names to be
|
||||
excluded from the form.
|
||||
|
||||
Either :attr:`~ModelFormOptions.fields` or
|
||||
:attr:`~ModelFormOptions.exclude` must be set. If neither are set, an
|
||||
:class:`~django.core.exceptions.ImproperlyConfigured` exception will be
|
||||
raised. If :attr:`~ModelFormOptions.exclude` is set and
|
||||
:attr:`~ModelFormOptions.fields` is unset, all model fields, except for
|
||||
those specified in :attr:`~ModelFormOptions.exclude`, are included in the
|
||||
form.
|
||||
|
||||
``field_classes``
|
||||
-----------------
|
||||
|
||||
.. attribute:: ModelFormOptions.field_classes
|
||||
|
||||
A dictionary that maps a model field name to a :class:`~django.forms.Field`
|
||||
class, which overrides the ``form_class`` used in the model field's
|
||||
:meth:`.Field.formfield` method.
|
||||
|
||||
When a field is not specified, Django will fall back on the model field's
|
||||
:ref:`default field class <model-form-field-types>`.
|
||||
|
||||
``fields``
|
||||
----------
|
||||
|
||||
.. attribute:: ModelFormOptions.fields
|
||||
|
||||
A tuple or list of :attr:`~ModelFormOptions.model` field names to be
|
||||
included in the form. The value ``'__all__'`` can be used to specify that
|
||||
all fields should be included.
|
||||
|
||||
If any field is specified in :attr:`~ModelFormOptions.exclude`, this will
|
||||
not be included in the form despite being specified in
|
||||
:attr:`~ModelFormOptions.fields`.
|
||||
|
||||
Either :attr:`~ModelFormOptions.fields` or
|
||||
:attr:`~ModelFormOptions.exclude` must be set. If neither are set, an
|
||||
:class:`~django.core.exceptions.ImproperlyConfigured` exception will be
|
||||
raised.
|
||||
|
||||
``formfield_callback``
|
||||
----------------------
|
||||
|
||||
.. attribute:: ModelFormOptions.formfield_callback
|
||||
|
||||
A function or callable that takes a model field and returns a
|
||||
:class:`django.forms.Field` object.
|
||||
|
||||
``help_texts``
|
||||
--------------
|
||||
|
||||
.. attribute:: ModelFormOptions.help_texts
|
||||
|
||||
A dictionary that maps a model field name to a help text string.
|
||||
|
||||
When a field is not specified, Django will fall back on that model field's
|
||||
:attr:`~django.db.models.Field.help_text`.
|
||||
|
||||
``labels``
|
||||
----------
|
||||
|
||||
.. attribute:: ModelFormOptions.labels
|
||||
|
||||
A dictionary that maps a model field names to a label string.
|
||||
|
||||
When a field is not specified, Django will fall back on that model field's
|
||||
:attr:`~django.db.models.Field.verbose_name` and then the field's attribute
|
||||
name.
|
||||
|
||||
``localized_fields``
|
||||
--------------------
|
||||
|
||||
.. attribute:: ModelFormOptions.localized_fields
|
||||
|
||||
A tuple or list of :attr:`~ModelFormOptions.model` field names to be
|
||||
localized. The value ``'__all__'`` can be used to specify that all fields
|
||||
should be localized.
|
||||
|
||||
By default, form fields are not localized, see
|
||||
:ref:`enabling localization of fields
|
||||
<modelforms-enabling-localization-of-fields>` for more details.
|
||||
|
||||
``model``
|
||||
---------
|
||||
|
||||
.. attribute:: ModelFormOptions.model
|
||||
|
||||
Required. The :class:`django.db.models.Model` to be used for the
|
||||
:class:`~django.forms.ModelForm`.
|
||||
|
||||
``widgets``
|
||||
-----------
|
||||
|
||||
.. attribute:: ModelFormOptions.widgets
|
||||
|
||||
A dictionary that maps a model field name to a
|
||||
:class:`django.forms.Widget`.
|
||||
|
||||
When a field is not specified, Django will fall back on the default widget
|
||||
for that particular type of :class:`django.db.models.Field`.
|
||||
|
||||
Model form factory functions
|
||||
============================
|
||||
|
||||
.. currentmodule:: django.forms.models
|
||||
|
||||
``modelform_factory``
|
||||
=====================
|
||||
---------------------
|
||||
|
||||
.. function:: modelform_factory(model, form=ModelForm, fields=None, exclude=None, formfield_callback=None, widgets=None, localized_fields=None, labels=None, help_texts=None, error_messages=None, field_classes=None)
|
||||
|
||||
|
|
@ -51,7 +224,7 @@ Model Form API reference. For introductory material about model forms, see the
|
|||
in an :exc:`~django.core.exceptions.ImproperlyConfigured` exception.
|
||||
|
||||
``modelformset_factory``
|
||||
========================
|
||||
------------------------
|
||||
|
||||
.. function:: modelformset_factory(model, form=ModelForm, formfield_callback=None, formset=BaseModelFormSet, extra=1, can_delete=False, can_order=False, max_num=None, fields=None, exclude=None, widgets=None, validate_max=False, localized_fields=None, labels=None, help_texts=None, error_messages=None, min_num=None, validate_min=False, field_classes=None, absolute_max=None, can_delete_extra=True, renderer=None, edit_only=False)
|
||||
|
||||
|
|
@ -74,7 +247,7 @@ Model Form API reference. For introductory material about model forms, see the
|
|||
See :ref:`model-formsets` for example usage.
|
||||
|
||||
``inlineformset_factory``
|
||||
=========================
|
||||
-------------------------
|
||||
|
||||
.. function:: inlineformset_factory(parent_model, model, form=ModelForm, formset=BaseInlineFormSet, fk_name=None, fields=None, exclude=None, extra=3, can_order=False, can_delete=True, max_num=None, formfield_callback=None, widgets=None, validate_max=False, localized_fields=None, labels=None, help_texts=None, error_messages=None, min_num=None, validate_min=False, field_classes=None, absolute_max=None, can_delete_extra=True, renderer=None, edit_only=False)
|
||||
|
||||
|
|
|
|||
|
|
@ -38,6 +38,8 @@ For example:
|
|||
>>> article = Article.objects.get(pk=1)
|
||||
>>> form = ArticleForm(instance=article)
|
||||
|
||||
.. _model-form-field-types:
|
||||
|
||||
Field types
|
||||
-----------
|
||||
|
||||
|
|
@ -683,6 +685,8 @@ the field declaratively and setting its ``validators`` parameter::
|
|||
See the :doc:`form field documentation </ref/forms/fields>` for more
|
||||
information on fields and their arguments.
|
||||
|
||||
.. _modelforms-enabling-localization-of-fields:
|
||||
|
||||
Enabling localization of fields
|
||||
-------------------------------
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user