1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
|
===========
Model forms
===========
.. module:: django.forms.models
: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)
Returns a :class:`~django.forms.ModelForm` class for the given ``model``.
You can optionally pass a ``form`` argument to use as a starting point for
constructing the ``ModelForm``.
``fields`` is an optional list of field names. If provided, only the named
fields will be included in the returned fields.
``exclude`` is an optional list of field names. If provided, the named
fields will be excluded from the returned fields, even if they are listed
in the ``fields`` argument.
``formfield_callback`` is a callable that takes a model field and returns
a form field.
``widgets`` is a dictionary of model field names mapped to a widget.
``localized_fields`` is a list of names of fields which should be
localized.
``labels`` is a dictionary of model field names mapped to a label.
``help_texts`` is a dictionary of model field names mapped to a help text.
``error_messages`` is a dictionary of model field names mapped to a
dictionary of error messages.
``field_classes`` is a dictionary of model field names mapped to a form
field class.
See :ref:`modelforms-factory` for example usage.
You must provide the list of fields explicitly, either via keyword
arguments ``fields`` or ``exclude``, or the corresponding attributes on the
form's inner ``Meta`` class. See :ref:`modelforms-selecting-fields` for
more information. Omitting any definition of the fields to use will result
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)
Returns a ``FormSet`` class for the given ``model`` class.
Arguments ``model``, ``form``, ``fields``, ``exclude``,
``formfield_callback``, ``widgets``, ``localized_fields``, ``labels``,
``help_texts``, ``error_messages``, and ``field_classes`` are all passed
through to :func:`~django.forms.models.modelform_factory`.
Arguments ``formset``, ``extra``, ``can_delete``, ``can_order``,
``max_num``, ``validate_max``, ``min_num``, ``validate_min``,
``absolute_max``, ``can_delete_extra``, and ``renderer`` are passed
through to :func:`~django.forms.formsets.formset_factory`. See
:doc:`formsets </topics/forms/formsets>` for details.
The ``edit_only`` argument allows :ref:`preventing new objects creation
<model-formsets-edit-only>`.
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)
Returns an ``InlineFormSet`` using :func:`modelformset_factory` with
defaults of ``formset=``:class:`~django.forms.models.BaseInlineFormSet`,
``can_delete=True``, and ``extra=3``.
If your model has more than one :class:`~django.db.models.ForeignKey` to
the ``parent_model``, you must specify a ``fk_name``.
See :ref:`inline-formsets` for example usage.
|
