Fixed #10239 - Added docs for modelform_factory

Thanks ingenieroariel for the suggestion and slurms for the review.
This commit is contained in:
Tim Graham 2013-01-11 05:59:17 -05:00
parent 4da5947a87
commit 71d76ec011
4 changed files with 100 additions and 7 deletions

View File

@ -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 ``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 fields will be excluded from the returned fields, even if they are listed
in the ``fields`` argument. 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 = [] field_list = []
ignored = [] ignored = []
@ -371,6 +376,21 @@ class ModelForm(six.with_metaclass(ModelFormMetaclass, BaseModelForm)):
def modelform_factory(model, form=ModelForm, fields=None, exclude=None, def modelform_factory(model, form=ModelForm, fields=None, exclude=None,
formfield_callback=None, widgets=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 # Create the inner Meta class. FIXME: ideally, we should be able to
# construct a ModelForm without creating and passing in a temporary # construct a ModelForm without creating and passing in a temporary
# inner class. # inner class.

View File

@ -9,5 +9,6 @@ Detailed form API reference. For introductory material, see :doc:`/topics/forms/
api api
fields fields
models
widgets widgets
validation validation

40
docs/ref/forms/models.txt Normal file
View File

@ -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 File

@ -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 :ref:`Validating objects <validating-objects>` for more information on the
model's ``clean()`` hook. 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:
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> <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:: .. note::
``modelformset_factory`` uses ``formset_factory`` to generate formsets.
This means that a model formset is just an extension of a basic formset :func:`~django.forms.models.modelformset_factory` uses ``formset_factory``
that knows how to interact with a particular model. 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 Changing the queryset
--------------------- ---------------------
@ -628,8 +656,9 @@ Providing initial values
As with regular formsets, it's possible to :ref:`specify initial data As with regular formsets, it's possible to :ref:`specify initial data
<formsets-initial-data>` for forms in the formset by specifying an ``initial`` <formsets-initial-data>` for forms in the formset by specifying an ``initial``
parameter when instantiating the model formset class returned by parameter when instantiating the model formset class returned by
``modelformset_factory``. However, with model formsets, the initial values only :func:`~django.forms.models.modelformset_factory`. However, with model
apply to extra forms, those that aren't bound to an existing object instance. formsets, the initial values only apply to extra forms, those that aren't bound
to an existing object instance.
.. _saving-objects-in-the-formset: .. _saving-objects-in-the-formset:
@ -675,7 +704,8 @@ Limiting the number of editable objects
--------------------------------------- ---------------------------------------
As with regular formsets, you can use the ``max_num`` and ``extra`` parameters 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:: ``max_num`` does not prevent existing objects from being displayed::
@ -850,7 +880,9 @@ a particular author, you could do this::
>>> formset = BookFormSet(instance=author) >>> formset = BookFormSet(instance=author)
.. note:: .. note::
``inlineformset_factory`` uses ``modelformset_factory`` and marks
``inlineformset_factory`` uses
:func:`~django.forms.models.modelformset_factory` and marks
``can_delete=True``. ``can_delete=True``.
.. seealso:: .. seealso::