Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Browse files

Added 'Adding related objects' section to docs/tutorial02.txt

git-svn-id: bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit af86b4e4b1a8a22dc8458bb0874ce2754ea85a6d 1 parent 5e309eb
@adrianholovaty adrianholovaty authored
Showing with 88 additions and 2 deletions.
  1. +88 −2 docs/tutorial02.txt
90 docs/tutorial02.txt
@@ -259,7 +259,93 @@ aren't commonly used::
.. image::
:alt: Fieldset is initially collapsed
-Customize the admin change list
+Adding related objects
+OK, we have our Poll admin page. But a ``Poll`` has multiple ``Choices``, and the admin
+page doesn't display choices.
+In this case, there are two ways to solve this problem. The first is to give
+the ``Choice`` model its own ``admin`` attribute, just as we did with ``Poll``.
+Here's what that would look like::
+ class Choice(meta.Model):
+ # ...
+ admin = meta.Admin(
+ fields = (
+ (None, {'fields': ('poll_id', 'choice', 'votes')}),
+ ),
+ )
+(Note that we used "poll_id" to refer to the ``ForeignKey(Poll)`` field. The
+field name is automatically calculated from the model's class name, lowercased,
+plus '_id'.)
+Now "Choices" is an available option in the Django admin. The "Add choice" form
+looks like this::
+.. image::
+ :alt: Choice admin page
+In that form, the "Poll" field is a select box containing every poll in the
+database. In our case, only one poll exists at this point.
+Also note the "Add Another" link next to "Poll." Every object with a ForeignKey
+relationship to another gets this for free. When you click "Add Another," you'll
+get a popup window with the "Add poll" form. If you add a poll in that window
+and click "Save," Django will save the poll to the database and dynamically add
+it as the selected choice on the "Add choice" form you're looking at.
+But, really, this is an inefficient way of adding Choice objects to the system.
+It'd be better if you could add a bunch of Choices directly when you create the
+Poll object. Let's make that happen.
+Remove the ``admin`` for the Choice model. Then, edit the ``ForeignKey(Poll)``
+field like so::
+ meta.ForeignKey(Poll, edit_inline=True, num_in_admin=3),
+This tells Django: "Choice objects are edited on the Poll admin page. By
+default, provide enough fields for 3 Choices."
+Then change the other fields in ``Choice`` to give them ``core=True``::
+ meta.CharField('choice', 'choice', maxlength=200, core=True),
+ meta.IntegerField('votes', 'votes', core=True),
+This tells Django: "When you edit a Choice on the Poll admin page, the 'choice'
+and 'votes' fields are required. The presence of at least one of them signifies
+the addition of a new Choice object, and clearing at least one of them
+signifies the deletion of that existing Choice object."
+Load the "Add poll" page to see how that looks:
+.. image::
+ :alt: Add poll page now has choices on it
+ :target:
+It works like this: There are three slots for related Choices -- as specified
+by ``num_in_admin`` -- but each time you come back to the "Change" page for an
+already-created object, you get one extra slot. (This means there's no
+hard-coded limit on how many related objects can be added.) If you wanted space
+for three extra Choices each time you changed the poll, you'd use
+One small problem, though. It takes a lot of screen space to display all the
+fields for entering related Choice objects. For that reason, Django offers an
+alternate way of displaying inline related objects::
+ meta.ForeignKey(Poll, edit_inline=True, num_in_admin=3, edit_inline_type=meta.TABULAR),
+With that ``edit_inline_type=meta.TABULAR``, the related objects are displayed
+in a more compact, table-based format:
+.. image::
+ :alt: Add poll page now has more compact choices
There's much more to come. This document is not finished.
Please sign in to comment.
Something went wrong with that request. Please try again.