Permalink
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...
timgraham committed Jan 11, 2013
1 parent 72ef63b commit c94fcc4117987c4ebe29ad63da01035230c8afd5
Showing with 100 additions and 7 deletions.
  1. +20 −0 django/forms/models.py
  2. +1 −0 docs/ref/forms/index.txt
  3. +40 −0 docs/ref/forms/models.txt
  4. +39 −7 docs/topics/forms/modelforms.txt
View
@@ -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
@@ -9,5 +9,6 @@ Detailed form API reference. For introductory material, see :doc:`/topics/forms/
api
fields
models
widgets
validation
View
@@ -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.
@@ -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::

0 comments on commit c94fcc4

Please sign in to comment.