Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Improved the docs even more.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@8864 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit a658d45a6c11798cd7d848d2d7aacde18ca173c0 1 parent 7163fe4
Brian Rosner authored September 02, 2008

Showing 1 changed file with 52 additions and 8 deletions. Show diff stats Hide diff stats

  1. 60  docs/topics/forms/modelforms.txt
60  docs/topics/forms/modelforms.txt
@@ -387,15 +387,16 @@ tricky with subclassing.
387 387
 Model Formsets
388 388
 ==============
389 389
 
390  
-Similar to regular formsets there are a couple enhanced formset classes that
391  
-provide all the right things to work with your models. Lets reuse the
392  
-``Author`` model from above::
  390
+Similar to :ref:`regular formsets <topics-forms-formsets>` there are a couple
  391
+enhanced formset classes that provide all the right things to work with your
  392
+models. Lets reuse the ``Author`` model from above::
393 393
 
394 394
     >>> from django.forms.models import modelformset_factory
395 395
     >>> AuthorFormSet = modelformset_factory(Author)
396 396
 
397 397
 This will create a formset that is capable of working with the data associated
398  
-to the ``Author`` model. It works just like a regular formset::
  398
+to the ``Author`` model. It works just like a regular formset just that we are
  399
+working with ``ModelForm`` instances instead of ``Form`` instances::
399 400
 
400 401
     >>> formset = AuthorFormSet()
401 402
     >>> print formset
@@ -435,6 +436,23 @@ be used as a base::
435 436
 
436 437
     >>> AuthorFormSet = modelformset_factory(Author, formset=BaseAuthorFormSet)
437 438
 
  439
+Controlling which fields are used with ``fields`` and ``exclude``
  440
+-----------------------------------------------------------------
  441
+
  442
+By default a model formset will use all fields in the model that are not marked
  443
+with ``editable=False``. However, this can be overidden at the formset level::
  444
+
  445
+    >>> AuthorFormSet = modelformset_factory(Author, fields=('name', 'title'))
  446
+
  447
+Using ``fields`` will restrict the formset to use just the given fields. Or if
  448
+you need to go the other way::
  449
+
  450
+    >>> AuthorFormSet = modelformset_factory(Author, exclude=('birth_date',))
  451
+
  452
+Using ``exclude`` will prevent the given fields from being used in the formset.
  453
+
  454
+.. _saving-objects-in-the-formset:
  455
+
438 456
 Saving objects in the formset
439 457
 -----------------------------
440 458
 
@@ -516,17 +534,43 @@ formset to a user to edit ``Author`` model instances::
516 534
 
517 535
 As you can see the view is not drastically different than how to use a formset
518 536
 in a view. The only difference is that we call ``formset.save()`` to save the
519  
-data into the database. This was describe above in :ref:`ref-saving-objects-in-the-formset`.
  537
+data into the database. This is described above in
  538
+:ref:`saving-objects-in-the-formset`.
520 539
 
521 540
 Using ``inlineformset_factory``
522 541
 -------------------------------
523 542
 
524 543
 The ``inlineformset_factory`` is a helper to a common usage pattern of working
525  
-with related objects through a foreign key. Suppose you have two models
526  
-``Author`` and ``Book``. You want to create a formset that works with the
527  
-books of a specific author. Here is how you could accomplish this::
  544
+with related objects through a foreign key. It takes all the same options as
  545
+a ``modelformset_factory``. Suppose you have these two models::
  546
+
  547
+    class Author(models.Model):
  548
+        name = models.CharField(max_length=100)
  549
+    
  550
+    class Book(models.Model):
  551
+        author = models.ForeignKey(Author)
  552
+        title = models.CharField(max_length=100)
  553
+
  554
+If you want to create a formset that allows you to edit books belonging to
  555
+some author you would do::
528 556
 
529 557
     >>> from django.forms.models import inlineformset_factory
530 558
     >>> BookFormSet = inlineformset_factory(Author, Book)
531 559
     >>> author = Author.objects.get(name=u'Orson Scott Card')
532 560
     >>> formset = BookFormSet(instance=author)
  561
+
  562
+More than one foriegn key to the same model
  563
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  564
+
  565
+If your model contains more than one foreign key to the same model you will
  566
+need to resolve the ambiguity manually using ``fk_name``. Given the following
  567
+model::
  568
+
  569
+    class Friendship(models.Model):
  570
+        from_friend = models.ForeignKey(Friend)
  571
+        to_friend = models.ForeignKey(Friend)
  572
+        length_in_months = models.IntegerField()
  573
+
  574
+To resolve this you can simply use ``fk_name`` to ``inlineformset_factory``::
  575
+
  576
+    >>> FrienshipFormSet = inlineformset_factory(Friend, Friendship, fk_name="from_friend")

0 notes on commit a658d45

Please sign in to comment.
Something went wrong with that request. Please try again.