From c94fcc4117987c4ebe29ad63da01035230c8afd5 Mon Sep 17 00:00:00 2001 From: Tim Graham Date: Fri, 11 Jan 2013 05:59:17 -0500 Subject: [1.5.x] Fixed #10239 - Added docs for modelform_factory Thanks ingenieroariel for the suggestion and slurms for the review. Backport of 71d76ec011 from master --- docs/topics/forms/modelforms.txt | 46 ++++++++++++++++++++++++++++++++++------ 1 file changed, 39 insertions(+), 7 deletions(-) (limited to 'docs/topics/forms') diff --git a/docs/topics/forms/modelforms.txt b/docs/topics/forms/modelforms.txt index 67d539447c..24699dbceb 100644 --- a/docs/topics/forms/modelforms.txt +++ b/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 ` 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:: .. 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 ` 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:: -- cgit v1.3