Ticket #6162: modelform-init-2.diff

django/newforms/models.py

@@ -262 +262 @@
         return type.__new__(cls, name, bases, attrs)
 
 class BaseModelForm(BaseForm):
-    def __init__(self, instance, data=None, files=None, auto_id='id_%s', prefix=None,
-                 initial=None, error_class=ErrorList, label_suffix=':'):
-        self.instance = instance
+    def __init__(self, data=None, files=None, auto_id='id_%s', prefix=None,
+                 initial=None, error_class=ErrorList, label_suffix=':', instance=None):
         opts = self._meta
-        object_data = model_to_dict(instance, opts.fields, opts.exclude)
+        if instance is None and opts.model is None:
+            raise ImproperlyConfigured("ModelForm must either be bound to a model class or receive a model instance in __init__()")
+        if instance is None:
+           self.instance = opts.model()
+           object_data = {}
+        else:
+            self.instance = instance
+            object_data = model_to_dict(instance, opts.fields, opts.exclude)
         # if initial was provided, it should override the values from instance
         if initial is not None:
             object_data.update(initial)

tests/modeltests/model_forms/models.py

@@ -29 +29 @@
     def __unicode__(self):
         return self.name
 
+class Editor(models.Model):
+    name = models.CharField(max_length=50, help_text='Use both first and last names.')
+    categories = models.ManyToManyField(Category)
+
+    def __unicode__(self):
+        return self.name
+
 class Article(models.Model):
     headline = models.CharField(max_length=50)
     slug = models.SlugField()
@@ -155 +162 @@
 ...
 ImproperlyConfigured: BadForm's base classes define more than one model.
 
+Require either a model bound in Meta or an instance passed in on __init__().
 
-# Old form_for_x tests #######################################################
+>>> class NoModelForm(ModelForm):
+...     pass
 
+>>> f = NoModelForm()
+Traceback (most recent call last):
+...
+ImproperlyConfigured: ModelForm must either be bound to a model class or receive a model instance in __init__()
+
+# Test valid ModelForms #######################################################
+
 >>> from django.newforms import ModelForm, CharField
 >>> import datetime
 
@@ -167 +183 @@
 >>> class CategoryForm(ModelForm):
 ...     class Meta:
 ...         model = Category
->>> f = CategoryForm(Category())
+>>> f = CategoryForm()
 >>> print f
 <tr><th><label for="id_name">Name:</label></th><td><input id="id_name" type="text" name="name" maxlength="20" /></td></tr>
 <tr><th><label for="id_slug">Slug:</label></th><td><input id="id_slug" type="text" name="slug" maxlength="20" /></td></tr>
@@ -179 +195 @@
 >>> print f['name']
 <input id="id_name" type="text" name="name" maxlength="20" />
 
->>> f = CategoryForm(Category(), auto_id=False)
+>>> f = CategoryForm(auto_id=False)
 >>> print f.as_ul()
 <li>Name: <input type="text" name="name" maxlength="20" /></li>
 <li>Slug: <input type="text" name="slug" maxlength="20" /></li>
 <li>The URL: <input type="text" name="url" maxlength="40" /></li>
 
->>> f = CategoryForm(Category(), {'name': 'Entertainment', 'slug': 'entertainment', 'url': 'entertainment'})
+>>> f = CategoryForm({'name': 'Entertainment', 'slug': 'entertainment', 'url': 'entertainment'})
 >>> f.is_valid()
 True
 >>> f.cleaned_data
@@ -196 +212 @@
 >>> Category.objects.all()
 [<Category: Entertainment>]
 
->>> f = CategoryForm(Category(), {'name': "It's a test", 'slug': 'its-test', 'url': 'test'})
+>>> f = CategoryForm({'name': "It's a test", 'slug': 'its-test', 'url': 'test'})
 >>> f.is_valid()
 True
 >>> f.cleaned_data
@@ -210 +226 @@
 If you call save() with commit=False, then it will return an object that
 hasn't yet been saved to the database. In this case, it's up to you to call
 save() on the resulting model instance.
->>> f = CategoryForm(Category(), {'name': 'Third test', 'slug': 'third-test', 'url': 'third'})
+>>> f = CategoryForm({'name': 'Third test', 'slug': 'third-test', 'url': 'third'})
 >>> f.is_valid()
 True
 >>> f.cleaned_data
@@ -225 +241 @@
 [<Category: Entertainment>, <Category: It's a test>, <Category: Third test>]
 
 If you call save() with invalid data, you'll get a ValueError.
->>> f = CategoryForm(Category(), {'name': '', 'slug': '', 'url': 'foo'})
+>>> f = CategoryForm({'name': '', 'slug': '', 'url': 'foo'})
 >>> f.errors
 {'name': [u'This field is required.'], 'slug': [u'This field is required.']}
 >>> f.cleaned_data
@@ -236 +252 @@
 Traceback (most recent call last):
 ...
 ValueError: The Category could not be created because the data didn't validate.
->>> f = CategoryForm(Category(), {'name': '', 'slug': '', 'url': 'foo'})
+>>> f = CategoryForm({'name': '', 'slug': '', 'url': 'foo'})
 >>> f.save()
 Traceback (most recent call last):
 ...
@@ -253 +269 @@
 >>> class ArticleForm(ModelForm):
 ...     class Meta:
 ...         model = Article
->>> f = ArticleForm(Article(), auto_id=False)
+>>> f = ArticleForm(auto_id=False)
 >>> print f
 <tr><th>Headline:</th><td><input type="text" name="headline" maxlength="50" /></td></tr>
 <tr><th>Slug:</th><td><input type="text" name="slug" maxlength="50" /></td></tr>
@@ -286 +302 @@
 ...     class Meta:
 ...         model = Article
 ...         fields = ('headline','pub_date')
->>> f = PartialArticleForm(Article(), auto_id=False)
+>>> f = PartialArticleForm(auto_id=False)
 >>> print f
 <tr><th>Headline:</th><td><input type="text" name="headline" maxlength="50" /></td></tr>
 <tr><th>Pub date:</th><td><input type="text" name="pub_date" /></td></tr>
 
-Use form_for_instance to create a Form from a model instance. The difference
-between this Form and one created via form_for_model is that the object's
+Pass the "instance" keyword argument to create a Form from a model instance. The
+difference between this Form and one created wthout the"instance" argument is that the object's
 current values are inserted as 'initial' data in each Field.
 >>> w = Writer.objects.get(name='Mike Royko')
 >>> class RoykoForm(ModelForm):
 ...     class Meta:
 ...         model = Writer
->>> f = RoykoForm(w, auto_id=False)
+>>> f = RoykoForm(auto_id=False, instance=w)
 >>> print f
 <tr><th>Name:</th><td><input type="text" name="name" value="Mike Royko" maxlength="50" /><br />Use both first and last names.</td></tr>
 
@@ -309 +325 @@
 >>> class TestArticleForm(ModelForm):
 ...     class Meta:
 ...         model = Article
->>> f = TestArticleForm(art, auto_id=False)
+>>> f = TestArticleForm(instance=art, auto_id=False)
 >>> print f.as_ul()
 <li>Headline: <input type="text" name="headline" value="Test article" maxlength="50" /></li>
 <li>Slug: <input type="text" name="slug" value="test-article" maxlength="50" /></li>
@@ -331 +347 @@
 <option value="2">It&#39;s a test</option>
 <option value="3">Third test</option>
 </select>  Hold down "Control", or "Command" on a Mac, to select more than one.</li>
->>> f = TestArticleForm(art, {'headline': u'Test headline', 'slug': 'test-headline', 'pub_date': u'1984-02-06', 'writer': u'1', 'article': 'Hello.'})
+>>> f = TestArticleForm({'headline': u'Test headline', 'slug': 'test-headline', 'pub_date': u'1984-02-06', 'writer': u'1', 'article': 'Hello.'}, instance=art)
 >>> f.is_valid()
 True
 >>> test_art = f.save()
@@ -347 +363 @@
 ...     class Meta:
 ...         model = Article
 ...         fields=('headline', 'slug', 'pub_date')
->>> f = PartialArticleForm(art, {'headline': u'New headline', 'slug': 'new-headline', 'pub_date': u'1988-01-04'}, auto_id=False)
+>>> f = PartialArticleForm({'headline': u'New headline', 'slug': 'new-headline', 'pub_date': u'1988-01-04'}, auto_id=False, instance=art)
 >>> print f.as_ul()
 <li>Headline: <input type="text" name="headline" value="New headline" maxlength="50" /></li>
 <li>Slug: <input type="text" name="slug" value="new-headline" maxlength="50" /></li>
@@ -370 +386 @@
 >>> class TestArticleForm(ModelForm):
 ...     class Meta:
 ...         model = Article
->>> f = TestArticleForm(new_art, auto_id=False)
+>>> f = TestArticleForm(auto_id=False, instance=new_art)
 >>> print f.as_ul()
 <li>Headline: <input type="text" name="headline" value="New headline" maxlength="50" /></li>
 <li>Slug: <input type="text" name="slug" value="new-headline" maxlength="50" /></li>
@@ -393 +409 @@
 <option value="3">Third test</option>
 </select>  Hold down "Control", or "Command" on a Mac, to select more than one.</li>
 
->>> f = TestArticleForm(new_art, {'headline': u'New headline', 'slug': u'new-headline', 'pub_date': u'1988-01-04',
-...     'writer': u'1', 'article': u'Hello.', 'categories': [u'1', u'2']})
+>>> f = TestArticleForm({'headline': u'New headline', 'slug': u'new-headline', 'pub_date': u'1988-01-04',
+...     'writer': u'1', 'article': u'Hello.', 'categories': [u'1', u'2']}, instance=new_art)
 >>> new_art = f.save()
 >>> new_art.id
 1
@@ -403 +419 @@
 [<Category: Entertainment>, <Category: It's a test>]
 
 Now, submit form data with no categories. This deletes the existing categories.
->>> f = TestArticleForm(new_art, {'headline': u'New headline', 'slug': u'new-headline', 'pub_date': u'1988-01-04',
-...     'writer': u'1', 'article': u'Hello.'})
+>>> f = TestArticleForm({'headline': u'New headline', 'slug': u'new-headline', 'pub_date': u'1988-01-04',
+...     'writer': u'1', 'article': u'Hello.'}, instance=new_art)
 >>> new_art = f.save()
 >>> new_art.id
 1
@@ -416 +432 @@
 >>> class ArticleForm(ModelForm):
 ...     class Meta:
 ...         model = Article
->>> f = ArticleForm(Article(), {'headline': u'The walrus was Paul', 'slug': u'walrus-was-paul', 'pub_date': u'1967-11-01',
+>>> f = ArticleForm({'headline': u'The walrus was Paul', 'slug': u'walrus-was-paul', 'pub_date': u'1967-11-01',
 ...     'writer': u'1', 'article': u'Test.', 'categories': [u'1', u'2']})
 >>> new_art = f.save()
 >>> new_art.id
@@ -429 +445 @@
 >>> class ArticleForm(ModelForm):
 ...     class Meta:
 ...         model = Article
->>> f = ArticleForm(Article(), {'headline': u'The walrus was Paul', 'slug': u'walrus-was-paul', 'pub_date': u'1967-11-01',
+>>> f = ArticleForm({'headline': u'The walrus was Paul', 'slug': u'walrus-was-paul', 'pub_date': u'1967-11-01',
 ...     'writer': u'1', 'article': u'Test.'})
 >>> new_art = f.save()
 >>> new_art.id
@@ -443 +459 @@
 >>> class ArticleForm(ModelForm):
 ...     class Meta:
 ...         model = Article
->>> f = ArticleForm(Article(), {'headline': u'The walrus was Paul', 'slug': 'walrus-was-paul', 'pub_date': u'1967-11-01',
+>>> f = ArticleForm({'headline': u'The walrus was Paul', 'slug': 'walrus-was-paul', 'pub_date': u'1967-11-01',
 ...     'writer': u'1', 'article': u'Test.', 'categories': [u'1', u'2']})
 >>> new_art = f.save(commit=False)
 
@@ -474 +490 @@
 <Category: Third test>
 >>> cat.id
 3
->>> form = ShortCategory(cat, {'name': 'Third', 'slug': 'third', 'url': '3rd'})
+>>> form = ShortCategory({'name': 'Third', 'slug': 'third', 'url': '3rd'}, instance=cat)
 >>> form.save()
 <Category: Third>
 >>> Category.objects.get(id=3)
@@ -486 +502 @@
 >>> class ArticleForm(ModelForm):
 ...     class Meta:
 ...         model = Article
->>> f = ArticleForm(Article(), auto_id=False)
+>>> f = ArticleForm(auto_id=False)
 >>> print f.as_ul()
 <li>Headline: <input type="text" name="headline" maxlength="50" /></li>
 <li>Slug: <input type="text" name="slug" maxlength="50" /></li>
@@ -536 +552 @@
 <option value="4">Fourth</option>
 </select>  Hold down "Control", or "Command" on a Mac, to select more than one.</li>
 
+By not binding the form to a specific model, and by explicitly
+specifying a list of fields, it's possible to use a ModelForm with any
+model which has fields of those names. Doing so requires that an
+instance be passed in on form instantiation.
+
+>>> class WriterOrEditorForm(ModelForm):
+...     name = forms.CharField(max_length=50)
+>>> w = Writer()
+>>> f = WriterOrEditorForm(instance=w)
+>>> print f.as_ul()
+<li><label for="id_name">Name:</label> <input id="id_name" type="text" name="name" maxlength="50" /></li>
+>>> e = Editor(name="Horace Greeley")
+>>> f = WriterOrEditorForm(instance=e)
+>>> print f.as_ul()
+<li><label for="id_name">Name:</label> <input id="id_name" type="text" name="name" value="Horace Greeley" maxlength="50" /></li>
+
+
 # ModelChoiceField ############################################################
 
 >>> from django.newforms import ModelChoiceField, ModelMultipleChoiceField
@@ -690 +723 @@
 >>> class PhoneNumberForm(ModelForm):
 ...     class Meta:
 ...         model = PhoneNumber
->>> f = PhoneNumberForm(PhoneNumber(), {'phone': '(312) 555-1212', 'description': 'Assistance'})
+>>> f = PhoneNumberForm({'phone': '(312) 555-1212', 'description': 'Assistance'})
 >>> f.is_valid()
 True
 >>> f.cleaned_data

docs/modelforms.txt

@@ -24 +24 @@
     ...         model = Article
 
     # Creating a form to add an article.
-    >>> article = Article()
-    >>> form = ArticleForm(article)
+    >>> form = ArticleForm()
 
     # Creating a form to change an existing article.
     >>> article = Article.objects.get(pk=1)
-    >>> form = ArticleForm(article)
+    >>> form = ArticleForm(instance=article)
 
 Field types
 -----------
@@ -166 +165 @@
 The ``save()`` method
 ---------------------
 
-Every form produced by ``ModelForm`` also has a ``save()`` method. This
-method creates and saves a database object from the data bound to the form.
-A subclass of ``ModelForm`` also requires a model instance as the first
-arument to its constructor. For example::
+Every form produced by ``ModelForm`` also has a ``save()``
+method. This method creates and saves a database object from the data
+bound to the form. A subclass of ``ModelForm`` can accept an existing
+model instance as the keyword argument ``instance``; if this is
+supplied, ``save()`` will update that instance. If it's not supplied,
+``save()`` will create a new instance of the specified model::
 
     # Create a form instance from POST data.
-    >>> a = Article()
-    >>> f = ArticleForm(a, request.POST)
+    >>> f = ArticleForm(request.POST)
 
     # Save a new Article object from the form's data.
     >>> new_article = f.save()
 
+    # Create a form to edit an existing Article.
+    >>> a = Article.objects.get(pk=1)
+    >>> f = ArticleForm(instance=a)
+
 Note that ``save()`` will raise a ``ValueError`` if the data in the form
 doesn't validate -- i.e., ``if form.errors``.
 
@@ -201 +205 @@
 ``save_m2m()`` to save the many-to-many form data. For example::
 
     # Create a form instance with POST data.
-    >>> a = Author()
-    >>> f = AuthorForm(a, request.POST)
+    >>> f = AuthorForm(request.POST)
 
     # Create, but don't save the new author instance.
     >>> new_author = f.save(commit=False)
@@ -222 +225 @@
 For example::
 
     # Create a form instance with POST data.
-    >>> a = Author()
-    >>> f = AuthorForm(a, request.POST)
+    >>> f = AuthorForm(request.POST)
 
     # Create and save the new author instance. There's no need to do anything else.
     >>> new_author = f.save()
@@ -277 +279 @@
     manually set anyextra required fields::
     
         instance = Instance(required_field='value')
-        form = InstanceForm(instance, request.POST)
+        form = InstanceForm(request.POST, instance=instance)
         new_instance = form.save()
 
         instance = form.save(commit=False)
@@ -289 +291 @@
 
 .. _section on saving forms: `The save() method`_
 
+Using a form with any of multiple models
+----------------------------------------
+
+If you have several models which share a common set of fields, and
+want to expose just those fields for editing, you can define a
+``ModelForm`` subclass *without* specifying the model, and list only
+the shared fields to be displayed.
+
+For example, if your application has multiple models which represent
+different types of people, each with a "name" field, you could define
+a ``ModelForm`` subclass like so::
+
+    from django import newforms as forms
+
+    class PersonNameForm(forms.ModelForm):
+        name = forms.CharField(max_length=50)
+
+You could then pass any instance of any model which has a "name" field
+as the ``instance`` keyword argument when creating an instance of the
+form.
+
+Note that when a ``ModelForm`` is used like this, two important
+restrictions apply:
+
+1. Only the fields which are explicitly declared on the form will be
+   displayed.
+
+2. It is your responsibility to supply values for any other required
+   fields before saving the model instance, either by filling them in
+   on the instance before passing it to the form, or by using the
+   ``commit=False`` argument to ``save()`` and then filling in the
+   fields before actually saving the instance to the databae.
+        
+Defining a ``ModelForm`` subclass without specifying a model, and then
+attempting to instantiate it without passing a model instance as the
+``instance`` keyword argument, is an error.
+
+
 Overriding the default field types
 ----------------------------------