Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Fixed #11795 -- Document (and slightly simplify) the use of inlines f…

…or m2m relations.

This is the first immediate benefit of m2m relations having an autogenerated model.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@11712 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit dab3e97c1a83a4c5482f50a671cbf2fc5e16c9ee 1 parent 53b2c38
Russell Keith-Magee authored November 03, 2009
3  django/db/models/fields/related.py
@@ -586,6 +586,9 @@ class ReverseManyRelatedObjectsDescriptor(object):
66  docs/ref/contrib/admin/index.txt
@@ -1048,16 +1048,68 @@ automatically::
1048 1048
             FriendshipInline,
1049 1049
         ]
1050 1050
 
  1051
+Working with Many-to-Many Models
  1052
+--------------------------------
  1053
+
  1054
+By default, admin widgets for many-to-many relations will be displayed
  1055
+on whichever model contains the actual reference to the ``ManyToManyField``.
  1056
+Depending on your ``ModelAdmin`` definition, each many-to-many field in your
  1057
+model will be represented by a standard HTML ``<select multiple>``, a
  1058
+horizontal or vertical filter, or a ``raw_id_admin`` widget. However, it is
  1059
+also possible to to replace these widgets with inlines.
  1060
+
  1061
+Suppose we have the following models::
  1062
+
  1063
+    class Person(models.Model):
  1064
+        name = models.CharField(max_length=128)
  1065
+
  1066
+    class Group(models.Model):
  1067
+        name = models.CharField(max_length=128)
  1068
+        members = models.ManyToManyField(Person, related_name='groups')
  1069
+
  1070
+If you want to display many-to-many relations using an inline, you can do
  1071
+so by defining an ``InlineModelAdmin`` object for the relationship.
  1072
+
  1073
+    class MembershipInline(admin.TabularInline):
  1074
+        model = Group.members.through
  1075
+
  1076
+    class PersonAdmin(admin.ModelAdmin):
  1077
+        inlines = [
  1078
+            MembershipInline,
  1079
+        ]
  1080
+
  1081
+    class GroupAdmin(admin.ModelAdmin):
  1082
+        inlines = [
  1083
+            MembershipInline,
  1084
+        ]
  1085
+        exclude = ('members',)
  1086
+
  1087
+There are two features worth noting in this example.
  1088
+
  1089
+Firstly - the ``MembershipInline`` class references ``Group.members.through``.
  1090
+The ``through`` attribute is a reference to the model that manages the
  1091
+many-to-many relation. This model is automatically created by Django when you
  1092
+define a many-to-many field.
  1093
+
  1094
+Secondly, the ``GroupAdmin`` must manually exclude the ``members`` field.
  1095
+Django displays an admin widget for a many-to-many field on the model that
  1096
+defines the relation (in this case, ``Group``). If you want to use an inline
  1097
+model to represent the many-to-many relationship, you must tell Django's admin
  1098
+to *not* display this widget - otherwise you will end up with two widgets on
  1099
+your admin page for managing the relation.
  1100
+
  1101
+In all other respects, the ``InlineModelAdmin`` is exactly the same as any
  1102
+other. You can customize the appearance using any of the normal
  1103
+``InlineModelAdmin`` properties.
  1104
+
1051 1105
 Working with Many-to-Many Intermediary Models
1052 1106
 ----------------------------------------------
1053 1107
 
1054  
-By default, admin widgets for many-to-many relations will be displayed inline
1055  
-on whichever model contains the actual reference to the ``ManyToManyField``.
1056  
-However, when you specify an intermediary model using the ``through``
1057  
-argument to a ``ManyToManyField``, the admin will not display a widget by
1058  
-default. This is because each instance of that intermediary model requires
1059  
-more information than could be displayed in a single widget, and the layout
1060  
-required for multiple widgets will vary depending on the intermediate model.
  1108
+When you specify an intermediary model using the ``through`` argument to a
  1109
+``ManyToManyField``, the admin will not display a widget by default. This is
  1110
+because each instance of that intermediary model requires more information
  1111
+than could be displayed in a single widget, and the layout required for
  1112
+multiple widgets will vary depending on the intermediate model.
1061 1113
 
1062 1114
 However, we still want to be able to edit that information inline. Fortunately,
1063 1115
 this is easy to do with inline admin models. Suppose we have the following

0 notes on commit dab3e97

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