Ticket #6095: docs.2.diff

docs/model-api.txt

@@ -976 +976 @@
 
     =======================  ============================================================
 
+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 via the usage of a ``through`` keyword argument to a
+``ManyToManyField`` -- 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()
+
+There are several elements 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, which is an
+``IntegerField``.  This will be used to store information about how many of 
+each topping, each pizza has.
+
+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 if a different database table name is needed.
+
+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
+with a normal ``ManyToManyField``.  ``Pizza`` model instances will now have 
+access to related toppings through the ``toppings`` descriptor, and ``Topping``
+model instances will now have access to related pizzas through the 
+``pizza_set`` descriptor.
+
+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(pk=1)
+    pepperoni = Topping.objects.get(pk=1)
+    pizza_topping = PizzaTopping(pizza=my_pizza, topping=pepperoni, num_toppings=25)
+    pizza_topping.save()
+
+.. note::
+    As soon as an intermediary model is specified, the ``add`` and 
+    ``remove`` methods become unavailable on the descriptors added by the 
+    ``ManyToManyField``.  For example, something like 
+    ``Pizza.toppings.add(pepperoni)`` will no longer work, as there is not
+    enough information given to fully create an intermediary model instance
+    (case in point: there's no information about ``num_toppings``--
+    a required field on ``PizzaTopping``).
+
+For more examples and ideas on how to work with intermediary models, 
+`see the tests`_.
+
+.. _see the tests: http://code.djangoproject.com/browser/django/trunk/tests/modeltests/m2m_manual/models.py
+
 One-to-one relationships
 ~~~~~~~~~~~~~~~~~~~~~~~~