Model forms¶
ModelForm API reference. For introductory material about using a
ModelForm, see the Creating forms from models topic guide.
Model form Meta API¶
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 model, and either
fields or exclude. All
other Meta attributes are optional.
Optional attributes, other than localized_fields and
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.
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.
error_messages¶
- 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
django.db.models.Field.error_messagesand then finally on the default error messages for that field type.
exclude¶
- ModelFormOptions.exclude¶
A tuple or list of
modelfield names to be excluded from the form.Either
fieldsorexcludemust be set. If neither are set, anImproperlyConfiguredexception will be raised. Ifexcludeis set andfieldsis unset, all model fields, except for those specified inexclude, are included in the form.
field_classes¶
- ModelFormOptions.field_classes¶
A dictionary that maps a model field name to a
Fieldclass, which overrides theform_classused in the model field’sField.formfield()method.When a field is not specified, Django will fall back on the model field’s default field class.
fields¶
- ModelFormOptions.fields¶
A tuple or list of
modelfield 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
exclude, this will not be included in the form despite being specified infields.Either
fieldsorexcludemust be set. If neither are set, anImproperlyConfiguredexception will be raised.
formfield_callback¶
- ModelFormOptions.formfield_callback¶
A function or callable that takes a model field and returns a
django.forms.Fieldobject.
help_texts¶
labels¶
- 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
verbose_nameand then the field’s attribute name.
localized_fields¶
- ModelFormOptions.localized_fields¶
A tuple or list of
modelfield 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 enabling localization of fields for more details.
model¶
- ModelFormOptions.model¶
Required. The
django.db.models.Modelto be used for theModelForm.
widgets¶
- ModelFormOptions.widgets¶
A dictionary that maps a model field name to a
django.forms.Widget.When a field is not specified, Django will fall back on the default widget for that particular type of
django.db.models.Field.
Model form factory functions¶
modelform_factory¶
- 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)[source]¶
Returns a
ModelFormclass for the givenmodel. You can optionally pass aformargument to use as a starting point for constructing theModelForm.fieldsis an optional list of field names. If provided, only the named fields will be included in the returned fields.excludeis an optional list of field names. If provided, the named fields will be excluded from the returned fields, even if they are listed in thefieldsargument.formfield_callbackis a callable that takes a model field and returns a form field.widgetsis a dictionary of model field names mapped to a widget.localized_fieldsis a list of names of fields which should be localized.labelsis a dictionary of model field names mapped to a label.help_textsis a dictionary of model field names mapped to a help text.error_messagesis a dictionary of model field names mapped to a dictionary of error messages.field_classesis a dictionary of model field names mapped to a form field class.See ModelForm factory function for example usage.
You must provide the list of fields explicitly, either via keyword arguments
fieldsorexclude, or the corresponding attributes on the form’s innerMetaclass. See Selecting the fields to use for more information. Omitting any definition of the fields to use will result in anImproperlyConfiguredexception.
modelformset_factory¶
- 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)[source]¶
Returns a
FormSetclass for the givenmodelclass.Arguments
model,form,fields,exclude,formfield_callback,widgets,localized_fields,labels,help_texts,error_messages, andfield_classesare all passed through tomodelform_factory().Arguments
formset,extra,can_delete,can_order,max_num,validate_max,min_num,validate_min,absolute_max,can_delete_extra, andrendererare passed through toformset_factory(). See formsets for details.The
edit_onlyargument allows preventing new objects creation.See Model formsets for example usage.
inlineformset_factory¶
- 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)[source]¶
Returns an
InlineFormSetusingmodelformset_factory()with defaults offormset=BaseInlineFormSet,can_delete=True, andextra=3.If your model has more than one
ForeignKeyto theparent_model, you must specify afk_name.See Inline formsets for example usage.
