Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

[1.5.x] Fixed #10239 - Added docs for modelform_factory

Thanks ingenieroariel for the suggestion and slurms for the review.

Backport of 71d76ec from master
  • Loading branch information...
commit c94fcc4117987c4ebe29ad63da01035230c8afd5 1 parent 72ef63b
@timgraham timgraham authored
View
20 django/forms/models.py
@@ -141,6 +141,11 @@ def fields_for_model(model, fields=None, exclude=None, widgets=None, formfield_c
``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.
+
+ ``widgets`` is a dictionary of model field names mapped to a widget
+
+ ``formfield_callback`` is a callable that takes a model field and returns
+ a form field.
"""
field_list = []
ignored = []
@@ -371,6 +376,21 @@ class ModelForm(six.with_metaclass(ModelFormMetaclass, BaseModelForm)):
def modelform_factory(model, form=ModelForm, fields=None, exclude=None,
formfield_callback=None, widgets=None):
+ """
+ Returns a ModelForm containing form fields for the given model.
+
+ ``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.
+
+ ``widgets`` is a dictionary of model field names mapped to a widget.
+
+ ``formfield_callback`` is a callable that takes a model field and returns
+ a form field.
+ """
# Create the inner Meta class. FIXME: ideally, we should be able to
# construct a ModelForm without creating and passing in a temporary
# inner class.
View
1  docs/ref/forms/index.txt
@@ -9,5 +9,6 @@ Detailed form API reference. For introductory material, see :doc:`/topics/forms/
api
fields
+ models
widgets
validation
View
40 docs/ref/forms/models.txt
@@ -0,0 +1,40 @@
+====================
+Model Form Functions
+====================
+
+.. module:: django.forms.models
+ :synopsis: Django's functions for building model forms and formsets.
+
+.. method:: modelform_factory(model, form=ModelForm, fields=None, exclude=None, formfield_callback=None, widgets=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.
+
+ ``widgets`` is a dictionary of model field names mapped to a widget.
+
+ ``formfield_callback`` is a callable that takes a model field and returns
+ a form field.
+
+ See :ref:`modelforms-factory` for example usage.
+
+.. method:: 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)
+
+ Returns a ``FormSet`` class for the given ``model`` class.
+
+ Arguments ``model``, ``form``, ``fields``, ``exclude``, and
+ ``formfield_callback`` are all passed through to
+ :meth:`~django.forms.models.modelform_factory`.
+
+ Arguments ``formset``, ``extra``, ``max_num``, ``can_order``, and
+ ``can_delete`` are passed through to ``formset_factory``. See
+ :ref:`formsets` for details.
+
+ See :ref:`model-formsets` for example usage.
View
46 docs/topics/forms/modelforms.txt
@@ -544,6 +544,33 @@ for more on how field cleaning and validation work. Also, your model's
:ref:`Validating objects <validating-objects>` for more information on the
model's ``clean()`` hook.
+.. _modelforms-factory:
+
+ModelForm factory function
+--------------------------
+
+You can create forms from a given model using the standalone function
+:class:`~django.forms.models.modelform_factory`, instead of using a class
+definition. This may be more convenient if you do not have many customizations
+to make::
+
+ >>> from django.forms.models import modelform_factory
+ >>> BookForm = modelform_factory(Book)
+
+This can also be used to make simple modifications to existing forms, for
+example by specifying which fields should be displayed::
+
+ >>> Form = modelform_factory(Book, form=BookForm, fields=("author",))
+
+... or which fields should be excluded::
+
+ >>> Form = modelform_factory(Book, form=BookForm, exclude=("title",))
+
+You can also specify the widgets to be used for a given field::
+
+ >>> from django.forms import Textarea
+ >>> Form = modelform_factory(Book, form=BookForm, widgets={"title": Textarea()})
+
.. _model-formsets:
Model formsets
@@ -574,9 +601,10 @@ with the ``Author`` model. It works just like a regular formset::
<tr><th><label for="id_form-0-birth_date">Birth date:</label></th><td><input type="text" name="form-0-birth_date" id="id_form-0-birth_date" /><input type="hidden" name="form-0-id" id="id_form-0-id" /></td></tr>
.. note::
- ``modelformset_factory`` uses ``formset_factory`` to generate formsets.
- This means that a model formset is just an extension of a basic formset
- that knows how to interact with a particular model.
+
+ :func:`~django.forms.models.modelformset_factory` uses ``formset_factory``
+ to generate formsets. This means that a model formset is just an extension
+ of a basic formset that knows how to interact with a particular model.
Changing the queryset
---------------------
@@ -630,8 +658,9 @@ Providing initial values
As with regular formsets, it's possible to :ref:`specify initial data
<formsets-initial-data>` for forms in the formset by specifying an ``initial``
parameter when instantiating the model formset class returned by
-``modelformset_factory``. However, with model formsets, the initial values only
-apply to extra forms, those that aren't bound to an existing object instance.
+:func:`~django.forms.models.modelformset_factory`. However, with model
+formsets, the initial values only apply to extra forms, those that aren't bound
+to an existing object instance.
.. _saving-objects-in-the-formset:
@@ -677,7 +706,8 @@ Limiting the number of editable objects
---------------------------------------
As with regular formsets, you can use the ``max_num`` and ``extra`` parameters
-to ``modelformset_factory`` to limit the number of extra forms displayed.
+to :func:`~django.forms.models.modelformset_factory` to limit the number of
+extra forms displayed.
``max_num`` does not prevent existing objects from being displayed::
@@ -852,7 +882,9 @@ a particular author, you could do this::
>>> formset = BookFormSet(instance=author)
.. note::
- ``inlineformset_factory`` uses ``modelformset_factory`` and marks
+
+ ``inlineformset_factory`` uses
+ :func:`~django.forms.models.modelformset_factory` and marks
``can_delete=True``.
.. seealso::
Please sign in to comment.
Something went wrong with that request. Please try again.