Code

Ticket #10239: 10239.diff

File 10239.diff, 7.3 KB (added by timo, 17 months ago)
Line 
1diff --git a/django/forms/models.py b/django/forms/models.py
2index e9b71cc..af78f0e 100644
3--- a/django/forms/models.py
4+++ b/django/forms/models.py
5@@ -141,6 +141,11 @@ def fields_for_model(model, fields=None, exclude=None, widgets=None, formfield_c
6     ``exclude`` is an optional list of field names. If provided, the named
7     fields will be excluded from the returned fields, even if they are listed
8     in the ``fields`` argument.
9+
10+    ``widgets`` is a dictionary of model field names mapped to a widget
11+
12+    ``formfield_callback`` is a callable that takes a model field and returns
13+    a form field.
14     """
15     field_list = []
16     ignored = []
17@@ -371,6 +376,21 @@ class ModelForm(six.with_metaclass(ModelFormMetaclass, BaseModelForm)):
18 
19 def modelform_factory(model, form=ModelForm, fields=None, exclude=None,
20                       formfield_callback=None,  widgets=None):
21+    """
22+    Returns a ModelForm containing form fields for the given model.
23+
24+    ``fields`` is an optional list of field names. If provided, only the named
25+    fields will be included in the returned fields.
26+
27+    ``exclude`` is an optional list of field names. If provided, the named
28+    fields will be excluded from the returned fields, even if they are listed
29+    in the ``fields`` argument.
30+
31+    ``widgets`` is a dictionary of model field names mapped to a widget.
32+
33+    ``formfield_callback`` is a callable that takes a model field and returns
34+    a form field.
35+    """
36     # Create the inner Meta class. FIXME: ideally, we should be able to
37     # construct a ModelForm without creating and passing in a temporary
38     # inner class.
39diff --git a/docs/ref/forms/index.txt b/docs/ref/forms/index.txt
40index 866afed..446fdb8 100644
41--- a/docs/ref/forms/index.txt
42+++ b/docs/ref/forms/index.txt
43@@ -9,5 +9,6 @@ Detailed form API reference. For introductory material, see :doc:`/topics/forms/
44 
45    api
46    fields
47+   models
48    widgets
49    validation
50diff --git a/docs/ref/forms/models.txt b/docs/ref/forms/models.txt
51new file mode 100644
52index 0000000..1f4a0d0
53--- /dev/null
54+++ b/docs/ref/forms/models.txt
55@@ -0,0 +1,40 @@
56+====================
57+Model Form Functions
58+====================
59+
60+.. module:: django.forms.models
61+   :synopsis: Django's functions for building model forms and formsets.
62+
63+.. method:: modelform_factory(model, form=ModelForm, fields=None, exclude=None, formfield_callback=None,  widgets=None)
64+
65+    Returns a :class:`~django.forms.ModelForm` class for the given ``model``.
66+    You can optionally pass a ``form`` argument to use as a starting point for
67+    constructing the ``ModelForm``.
68+
69+    ``fields`` is an optional list of field names. If provided, only the named
70+    fields will be included in the returned fields.
71+
72+    ``exclude`` is an optional list of field names. If provided, the named
73+    fields will be excluded from the returned fields, even if they are listed
74+    in the ``fields`` argument.
75+
76+    ``widgets`` is a dictionary of model field names mapped to a widget.
77+
78+    ``formfield_callback`` is a callable that takes a model field and returns
79+    a form field.
80+
81+    See :ref:`modelforms-factory` for example usage.
82+
83+.. 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)
84+
85+    Returns a ``FormSet`` class for the given ``model`` class.
86+
87+    Arguments ``model``, ``form``, ``fields``, ``exclude``, and
88+    ``formfield_callback`` are all passed through to
89+    :meth:`~django.forms.models.modelform_factory`.
90+
91+    Arguments ``formset``, ``extra``, ``max_num``, ``can_order``, and
92+    ``can_delete`` are passed through to ``formset_factory``. See
93+    :ref:`formsets` for details.
94+
95+    See :ref:`model-formsets` for example usage.
96diff --git a/docs/topics/forms/modelforms.txt b/docs/topics/forms/modelforms.txt
97index fcc9bd6..9c97b34 100644
98--- a/docs/topics/forms/modelforms.txt
99+++ b/docs/topics/forms/modelforms.txt
100@@ -547,6 +547,33 @@ for more on how field cleaning and validation work. Also, your model's
101 :ref:`Validating objects <validating-objects>` for more information on the
102 model's ``clean()`` hook.
103 
104+.. _modelforms-factory:
105+
106+ModelForm factory function
107+--------------------------
108+
109+You can create forms from a given model using the standalone function
110+:class:`~django.forms.models.modelform_factory`, instead of using a class
111+definition. This  may be more convenient if you do not have many customizations
112+to make::
113+
114+    >>> from django.forms.models import modelform_factory
115+    >>> BookForm = modelform_factory(Book)
116+
117+This can also be used to make simple modifications to existing forms, for
118+example by specifying which fields should be displayed::
119+
120+    >>> Form = modelform_factory(Book, form=BookForm, fields=("author",))
121+
122+... or which fields should be excluded::
123+
124+    >>> Form = modelform_factory(Book, form=BookForm, exclude=("title",))
125+
126+You can also specify the widgets to be used for a given field::
127+
128+    >>> from django.forms import Textarea
129+    >>> Form = modelform_factory(Book, form=BookForm, widgets={"title": Textarea()})
130+
131 .. _model-formsets:
132 
133 Model formsets
134@@ -575,9 +602,10 @@ with the ``Author`` model. It works just like a regular formset::
135     <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>
136 
137 .. note::
138-    ``modelformset_factory`` uses ``formset_factory`` to generate formsets.
139-    This means that a model formset is just an extension of a basic formset
140-    that knows how to interact with a particular model.
141+
142+    :func:`~django.forms.models.modelformset_factory` uses ``formset_factory``
143+    to generate formsets. This means that a model formset is just an extension
144+    of a basic formset that knows how to interact with a particular model.
145 
146 Changing the queryset
147 ---------------------
148@@ -631,8 +659,9 @@ Providing initial values
149 As with regular formsets, it's possible to :ref:`specify initial data
150 <formsets-initial-data>` for forms in the formset by specifying an ``initial``
151 parameter when instantiating the model formset class returned by
152-``modelformset_factory``. However, with model formsets, the initial values only
153-apply to extra forms, those that aren't bound to an existing object instance.
154+:func:`~django.forms.models.modelformset_factory`. However, with model
155+formsets, the initial values only apply to extra forms, those that aren't bound
156+to an existing object instance.
157 
158 .. _saving-objects-in-the-formset:
159 
160@@ -678,7 +707,8 @@ Limiting the number of editable objects
161 ---------------------------------------
162 
163 As with regular formsets, you can use the ``max_num`` and ``extra`` parameters
164-to ``modelformset_factory`` to limit the number of extra forms displayed.
165+to :func:`~django.forms.models.modelformset_factory` to limit the number of
166+extra forms displayed.
167 
168 ``max_num`` does not prevent existing objects from being displayed::
169 
170@@ -853,7 +883,8 @@ a particular author, you could do this::
171     >>> formset = BookFormSet(instance=author)
172 
173 .. note::
174-    ``inlineformset_factory`` uses ``modelformset_factory`` and marks
175+    ``inlineformset_factory`` uses
176+    :func:`~django.forms.models.modelformset_factory` and marks
177     ``can_delete=True``.
178 
179 .. seealso::