Ticket #6095: docs.diff

docs/model-api.txt

@@ -975 +975 @@
-                             name based upon the names of the two tables being joined.
-
-    =======================  ============================================================
+
+Many-to-many relationships with an intermediary model
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sometimes many-to-many relationships require a bit more definition than a 
+standard ``ManyToManyField`` will allow.  For example, suppose that ``Topping``
+object was pepperoni, and that you wanted to keep track of how many pepperoni 
+there were on each pizza.  In that case, Django allows for the specification of
+an intermediary model -- Here's how that might look::
+
+    class Topping(models.Model):
+        # ...
+
+    class Pizza(models.Model):
+        # ...
+        toppings = models.ManyToManyField(Topping, through='PizzaTopping')
+    
+    class PizzaTopping(models.Model):
+        pizza = models.ForeignKey(Pizza)
+        topping = models.ForeignKey(Topping)
+        num_toppings = models.IntegerField(default=1)
+
+There are several things at play in this example.  The first thing to note is 
+that a new model has been created named ``PizzaTopping`` (in your own 
+applications, it can be named anything.  It need not be a concatenation of the 
+two related model names) which has two ``ForeignKey`` relationships:: one to 
+``Pizza``, and another to ``Topping``.
+
+The third field on our new ``PizzaTopping`` model is num_toppings, an 
+``IntegerField``.  This will be used to store information about how many of 
+each topping each pizza has.
+
+**NOTE:** Any extra fields on an intermediary model must either be nullable
+(``null``=True), or have a default value.
+
+To complete this intermediary many-to-many definition, it is necessary to link
+the intermediary model with the ``ManyToManyField``.  Doing so requires the use
+of the ``through`` property on the ``ManyToManyField``.  This must be a string
+representation of the intermediary model--in this case, ``PizzaTopping``.
+
+If you would like to specify a database table for the intermediary 
+relationship, setting the db_table property on a ``ManyToManyField`` will no 
+longer work correctly.  Instead, set the db_table property on the intermediary
+model's inner ``Meta`` class.
+
+Now that you've got your intermediary model set up and you have it attached as 
+a ``ManyToManyField`` to Pizza, you can access the related data the same way as
+normal.  ``Pizza`` model instances will now have access to related toppings 
+through the ``toppings`` attribute, and ``Topping`` model instances will now 
+have access to related pizzas through the ``pizza_set`` attribute.
+
+The additional information (in this case, num_toppings) is available by 
+accessing the intermediary model just like you would access any other model.
+
+Example::
+    
+    my_pizza = Pizza.objects.get(id=1)
+    pepperoni = Topping.objects.get(id=1)
+    pizza_topping = PizzaTopping.objects.get(pizza=my_pizza, topping=pepperoni)
+    pizza_topping.num_toppings = 25
+    pizza_topping.save()
+    
+For more examples on how to work with ``ManyToManyField``s, `see the tests`_.
+
+.. _see the tests: http://code.djangoproject.com/browser/django/trunk/tests/modeltests/m2m_manual/models.py
-
-One-to-one relationships
-~~~~~~~~~~~~~~~~~~~~~~~~