Debian Codegraph @

docs/ref/forms/models.txt

raw
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.