| 1 |
=========== |
| 2 |
Model forms |
| 3 |
=========== |
| 4 |
|
| 5 |
.. module:: django.forms.models |
| 6 |
:synopsis: ModelForm API reference for inner ``Meta`` class and factory |
| 7 |
functions |
| 8 |
|
| 9 |
.. currentmodule:: django.forms |
| 10 |
|
| 11 |
``ModelForm`` API reference. For introductory material about using a |
| 12 |
``ModelForm``, see the :doc:`/topics/forms/modelforms` topic guide. |
| 13 |
|
| 14 |
Model form ``Meta`` API |
| 15 |
======================= |
| 16 |
|
| 17 |
.. class:: ModelFormOptions |
| 18 |
|
| 19 |
The ``_meta`` API is used to build forms that reflect a Django model. It is |
| 20 |
accessible through the ``_meta`` attribute of each model form, and is an |
| 21 |
``django.forms.models.ModelFormOptions`` instance. |
| 22 |
|
| 23 |
The structure of the generated form can be customized by defining metadata |
| 24 |
options as attributes of an inner ``Meta`` class. For example:: |
| 25 |
|
| 26 |
from django.forms import ModelForm |
| 27 |
from myapp.models import Book |
| 28 |
|
| 29 |
|
| 30 |
class BookForm(ModelForm): |
| 31 |
class Meta: |
| 32 |
model = Book |
| 33 |
fields = ["title", "author"] |
| 34 |
help_texts = { |
| 35 |
"title": "The title of the book", |
| 36 |
"author": "The author of the book", |
| 37 |
} |
| 38 |
# ... other attributes |
| 39 |
|
| 40 |
Required attributes are :attr:`~ModelFormOptions.model`, and either |
| 41 |
:attr:`~ModelFormOptions.fields` or :attr:`~ModelFormOptions.exclude`. All |
| 42 |
other ``Meta`` attributes are optional. |
| 43 |
|
| 44 |
Optional attributes, other than :attr:`~ModelFormOptions.localized_fields` and |
| 45 |
:attr:`~ModelFormOptions.formfield_callback`, expect a dictionary that maps a |
| 46 |
model field name to a value. Any field that is not defined in the dictionary |
| 47 |
falls back to the field's default value. |
| 48 |
|
| 49 |
.. admonition:: Invalid field names |
| 50 |
|
| 51 |
Invalid or excluded field names in an optional dictionary attribute have no |
| 52 |
effect, since fields that are not included are not accessed. |
| 53 |
|
| 54 |
.. admonition:: Invalid Meta class attributes |
| 55 |
|
| 56 |
You may define any attribute on a ``Meta`` class. Typos or incorrect |
| 57 |
attribute names do not raise an error. |
| 58 |
|
| 59 |
``error_messages`` |
| 60 |
------------------ |
| 61 |
|
| 62 |
.. attribute:: ModelFormOptions.error_messages |
| 63 |
|
| 64 |
A dictionary that maps a model field name to a dictionary of error message |
| 65 |
keys (``null``, ``blank``, ``invalid``, ``unique``, etc.) mapped to custom |
| 66 |
error messages. |
| 67 |
|
| 68 |
When a field is not specified, Django will fall back on the error messages |
| 69 |
defined in that model field's :attr:`django.db.models.Field.error_messages` |
| 70 |
and then finally on the default error messages for that field type. |
| 71 |
|
| 72 |
``exclude`` |
| 73 |
----------- |
| 74 |
|
| 75 |
.. attribute:: ModelFormOptions.exclude |
| 76 |
|
| 77 |
A tuple or list of :attr:`~ModelFormOptions.model` field names to be |
| 78 |
excluded from the form. |
| 79 |
|
| 80 |
Either :attr:`~ModelFormOptions.fields` or |
| 81 |
:attr:`~ModelFormOptions.exclude` must be set. If neither are set, an |
| 82 |
:class:`~django.core.exceptions.ImproperlyConfigured` exception will be |
| 83 |
raised. If :attr:`~ModelFormOptions.exclude` is set and |
| 84 |
:attr:`~ModelFormOptions.fields` is unset, all model fields, except for |
| 85 |
those specified in :attr:`~ModelFormOptions.exclude`, are included in the |
| 86 |
form. |
| 87 |
|
| 88 |
``field_classes`` |
| 89 |
----------------- |
| 90 |
|
| 91 |
.. attribute:: ModelFormOptions.field_classes |
| 92 |
|
| 93 |
A dictionary that maps a model field name to a :class:`~django.forms.Field` |
| 94 |
class, which overrides the ``form_class`` used in the model field's |
| 95 |
:meth:`.Field.formfield` method. |
| 96 |
|
| 97 |
When a field is not specified, Django will fall back on the model field's |
| 98 |
:ref:`default field class <model-form-field-types>`. |
| 99 |
|
| 100 |
``fields`` |
| 101 |
---------- |
| 102 |
|
| 103 |
.. attribute:: ModelFormOptions.fields |
| 104 |
|
| 105 |
A tuple or list of :attr:`~ModelFormOptions.model` field names to be |
| 106 |
included in the form. The value ``'__all__'`` can be used to specify that |
| 107 |
all fields should be included. |
| 108 |
|
| 109 |
If any field is specified in :attr:`~ModelFormOptions.exclude`, this will |
| 110 |
not be included in the form despite being specified in |
| 111 |
:attr:`~ModelFormOptions.fields`. |
| 112 |
|
| 113 |
Either :attr:`~ModelFormOptions.fields` or |
| 114 |
:attr:`~ModelFormOptions.exclude` must be set. If neither are set, an |
| 115 |
:class:`~django.core.exceptions.ImproperlyConfigured` exception will be |
| 116 |
raised. |
| 117 |
|
| 118 |
``formfield_callback`` |
| 119 |
---------------------- |
| 120 |
|
| 121 |
.. attribute:: ModelFormOptions.formfield_callback |
| 122 |
|
| 123 |
A function or callable that takes a model field and returns a |
| 124 |
:class:`django.forms.Field` object. |
| 125 |
|
| 126 |
``help_texts`` |
| 127 |
-------------- |
| 128 |
|
| 129 |
.. attribute:: ModelFormOptions.help_texts |
| 130 |
|
| 131 |
A dictionary that maps a model field name to a help text string. |
| 132 |
|
| 133 |
When a field is not specified, Django will fall back on that model field's |
| 134 |
:attr:`~django.db.models.Field.help_text`. |
| 135 |
|
| 136 |
``labels`` |
| 137 |
---------- |
| 138 |
|
| 139 |
.. attribute:: ModelFormOptions.labels |
| 140 |
|
| 141 |
A dictionary that maps a model field names to a label string. |
| 142 |
|
| 143 |
When a field is not specified, Django will fall back on that model field's |
| 144 |
:attr:`~django.db.models.Field.verbose_name` and then the field's attribute |
| 145 |
name. |
| 146 |
|
| 147 |
``localized_fields`` |
| 148 |
-------------------- |
| 149 |
|
| 150 |
.. attribute:: ModelFormOptions.localized_fields |
| 151 |
|
| 152 |
A tuple or list of :attr:`~ModelFormOptions.model` field names to be |
| 153 |
localized. The value ``'__all__'`` can be used to specify that all fields |
| 154 |
should be localized. |
| 155 |
|
| 156 |
By default, form fields are not localized, see |
| 157 |
:ref:`enabling localization of fields |
| 158 |
<modelforms-enabling-localization-of-fields>` for more details. |
| 159 |
|
| 160 |
``model`` |
| 161 |
--------- |
| 162 |
|
| 163 |
.. attribute:: ModelFormOptions.model |
| 164 |
|
| 165 |
Required. The :class:`django.db.models.Model` to be used for the |
| 166 |
:class:`~django.forms.ModelForm`. |
| 167 |
|
| 168 |
``widgets`` |
| 169 |
----------- |
| 170 |
|
| 171 |
.. attribute:: ModelFormOptions.widgets |
| 172 |
|
| 173 |
A dictionary that maps a model field name to a |
| 174 |
:class:`django.forms.Widget`. |
| 175 |
|
| 176 |
When a field is not specified, Django will fall back on the default widget |
| 177 |
for that particular type of :class:`django.db.models.Field`. |
| 178 |
|
| 179 |
Model form factory functions |
| 180 |
============================ |
| 181 |
|
| 182 |
.. currentmodule:: django.forms.models |
| 183 |
|
| 184 |
``modelform_factory`` |
| 185 |
--------------------- |
| 186 |
|
| 187 |
.. 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) |
| 188 |
|
| 189 |
Returns a :class:`~django.forms.ModelForm` class for the given ``model``. |
| 190 |
You can optionally pass a ``form`` argument to use as a starting point for |
| 191 |
constructing the ``ModelForm``. |
| 192 |
|
| 193 |
``fields`` is an optional list of field names. If provided, only the named |
| 194 |
fields will be included in the returned fields. |
| 195 |
|
| 196 |
``exclude`` is an optional list of field names. If provided, the named |
| 197 |
fields will be excluded from the returned fields, even if they are listed |
| 198 |
in the ``fields`` argument. |
| 199 |
|
| 200 |
``formfield_callback`` is a callable that takes a model field and returns |
| 201 |
a form field. |
| 202 |
|
| 203 |
``widgets`` is a dictionary of model field names mapped to a widget. |
| 204 |
|
| 205 |
``localized_fields`` is a list of names of fields which should be localized. |
| 206 |
|
| 207 |
``labels`` is a dictionary of model field names mapped to a label. |
| 208 |
|
| 209 |
``help_texts`` is a dictionary of model field names mapped to a help text. |
| 210 |
|
| 211 |
``error_messages`` is a dictionary of model field names mapped to a |
| 212 |
dictionary of error messages. |
| 213 |
|
| 214 |
``field_classes`` is a dictionary of model field names mapped to a form |
| 215 |
field class. |
| 216 |
|
| 217 |
See :ref:`modelforms-factory` for example usage. |
| 218 |
|
| 219 |
You must provide the list of fields explicitly, either via keyword arguments |
| 220 |
``fields`` or ``exclude``, or the corresponding attributes on the form's |
| 221 |
inner ``Meta`` class. See :ref:`modelforms-selecting-fields` for more |
| 222 |
information. Omitting any definition of the fields to use will result in |
| 223 |
an :exc:`~django.core.exceptions.ImproperlyConfigured` exception. |
| 224 |
|
| 225 |
``modelformset_factory`` |
| 226 |
------------------------ |
| 227 |
|
| 228 |
.. 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) |
| 229 |
|
| 230 |
Returns a ``FormSet`` class for the given ``model`` class. |
| 231 |
|
| 232 |
Arguments ``model``, ``form``, ``fields``, ``exclude``, |
| 233 |
``formfield_callback``, ``widgets``, ``localized_fields``, ``labels``, |
| 234 |
``help_texts``, ``error_messages``, and ``field_classes`` are all passed |
| 235 |
through to :func:`~django.forms.models.modelform_factory`. |
| 236 |
|
| 237 |
Arguments ``formset``, ``extra``, ``can_delete``, ``can_order``, |
| 238 |
``max_num``, ``validate_max``, ``min_num``, ``validate_min``, |
| 239 |
``absolute_max``, ``can_delete_extra``, and ``renderer`` are passed |
| 240 |
through to :func:`~django.forms.formsets.formset_factory`. See |
| 241 |
:doc:`formsets </topics/forms/formsets>` for details. |
| 242 |
|
| 243 |
The ``edit_only`` argument allows :ref:`preventing new objects creation |
| 244 |
<model-formsets-edit-only>`. |
| 245 |
|
| 246 |
See :ref:`model-formsets` for example usage. |
| 247 |
|
| 248 |
``inlineformset_factory`` |
| 249 |
------------------------- |
| 250 |
|
| 251 |
.. 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) |
| 252 |
|
| 253 |
Returns an ``InlineFormSet`` using :func:`modelformset_factory` with |
| 254 |
defaults of ``formset=``:class:`~django.forms.models.BaseInlineFormSet`, |
| 255 |
``can_delete=True``, and ``extra=3``. |
| 256 |
|
| 257 |
If your model has more than one :class:`~django.db.models.ForeignKey` to |
| 258 |
the ``parent_model``, you must specify a ``fk_name``. |
| 259 |
|
| 260 |
See :ref:`inline-formsets` for example usage. |