diff options
Diffstat (limited to 'docs/modelforms.txt')
| -rw-r--r-- | docs/modelforms.txt | 33 |
1 files changed, 18 insertions, 15 deletions
diff --git a/docs/modelforms.txt b/docs/modelforms.txt index 8580fe1dbd..0136540bed 100644 --- a/docs/modelforms.txt +++ b/docs/modelforms.txt @@ -24,12 +24,11 @@ For example:: ... 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,18 +165,23 @@ we'll discuss in a moment.):: 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,8 +205,7 @@ you've manually saved the instance produced by the form, you can invoke ``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) @@ -274,10 +277,10 @@ model fields: any attempt to ``save()`` a ``ModelForm`` with missing fields will fail. To avoid this failure, you must instantiate your model with initial values for the missing, but required fields, or use ``save(commit=False)`` and - manually set anyextra required fields:: + manually set any extra required fields:: - instance = Instance(requiured_field='value') - form = InstanceForm(instance, request.POST) + instance = Instance(required_field='value') + form = InstanceForm(request.POST, instance=instance) new_instance = form.save() instance = form.save(commit=False) @@ -293,7 +296,7 @@ Overriding the default field types ---------------------------------- The default field types, as described in the "Field types" table above, are -sensible defaults; if you have a ``DateField`` in your model, chances are you'd +sensible defaults. If you have a ``DateField`` in your model, chances are you'd want that to be represented as a ``DateField`` in your form. But ``ModelForm`` gives you the flexibility of changing the form field type for a given model field. You do this by declaratively specifying fields like |