diff --git a/django/forms/models.py b/django/forms/models.py index 27c246b668..1b6821cd5b 100644 --- a/django/forms/models.py +++ b/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. diff --git a/docs/ref/forms/index.txt b/docs/ref/forms/index.txt index 866afed6dc..446fdb82de 100644 --- a/docs/ref/forms/index.txt +++ b/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 diff --git a/docs/ref/forms/models.txt b/docs/ref/forms/models.txt new file mode 100644 index 0000000000..1f4a0d0c3d --- /dev/null +++ b/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. diff --git a/docs/topics/forms/modelforms.txt b/docs/topics/forms/modelforms.txt index 802150d6c3..9a33d68cf7 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 --------------------- @@ -628,8 +656,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: @@ -675,7 +704,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:: @@ -850,7 +880,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::