Ticket #1464: tutorial02.patch

File tutorial02.patch, 7.2 KB (added by jbowtie@…, 9 years ago)

Tutorial 2 - this one is pretty complete, I think.

  • docs/tutorial02.txt

     
    8383
    8484Just one thing to do: We need to specify in the ``Poll`` model that ``Poll``
    8585objects have an admin interface. Edit the ``myproject/polls/models/polls.py``
    86 file and make the following change to add an inner ``Meta`` class with an
    87 ``admin`` attribute::
     86file and make the following change to add an inner ``Admin`` class::
    8887
    89     class Poll(meta.Model):
     88    class Poll(models.Model):
    9089        # ...
    91         class Meta:
    92             admin = meta.Admin()
     90        class Admin:
     91            pass
    9392
    94 The ``class Meta`` contains all `non-field metadata`_ about this model.
     93The ``class Admin`` will contain all `administrative metadata` about this model.
    9594
    9695Now reload the Django admin page to see your changes. Note that you don't have
    9796to restart the development server -- it auto-reloads code.
    9897
    99 .. _non-field metadata: http://www.djangoproject.com/documentation/model_api/#meta-options
    100 
    10198Explore the free admin functionality
    10299====================================
    103100
    104 Now that ``Poll`` has the ``admin`` attribute, Django knows that it should be
     101Now that ``Poll`` has the inner ``Admin`` class, Django knows that it should be
    105102displayed on the admin index page:
    106103
    107104.. image:: http://media.djangoproject.com/img/doc/tutorial/admin03t.png
     
    125122Things to note here:
    126123
    127124* The form is automatically generated from the Poll model.
    128 * The different model field types (``meta.DateTimeField``, ``meta.CharField``)
     125* The different model field types (``models.DateTimeField``, ``models.CharField``)
    129126  correspond to the appropriate HTML input widget. Each type of field knows
    130127  how to display itself in the Django admin.
    131128* Each ``DateTimeField`` gets free JavaScript shortcuts. Dates get a "Today"
     
    157154Take a few minutes to marvel at all the code you didn't have to write.
    158155
    159156Let's customize this a bit. We can reorder the fields by explicitly adding a
    160 ``fields`` parameter to ``meta.Admin``::
     157``fields`` parameter to ``Admin``::
    161158
    162         admin = meta.Admin(
     159        class Admin:
    163160            fields = (
    164161                (None, {'fields': ('pub_date', 'question')}),
    165             ),
    166         )
     162            )
    167163
    168164That made the "Publication date" show up first instead of second:
    169165
     
    176172And speaking of forms with dozens of fields, you might want to split the form
    177173up into fieldsets::
    178174
    179         admin = meta.Admin(
     175        class Admin:
    180176            fields = (
    181177                (None, {'fields': ('question',)}),
    182178                ('Date information', {'fields': ('pub_date',)}),
    183             ),
    184         )
     179            )
    185180
    186181The first element of each tuple in ``fields`` is the title of the fieldset.
    187182Here's what our form looks like now:
     
    195190This is useful when you have a long form that contains a number of fields that
    196191aren't commonly used::
    197192
    198         admin = meta.Admin(
     193        class Admin:
    199194            fields = (
    200195                (None, {'fields': ('question',)}),
    201196                ('Date information', {'fields': ('pub_date',), 'classes': 'collapse'}),
    202             ),
    203         )
     197            )
    204198
    205199.. image:: http://media.djangoproject.com/img/doc/tutorial/admin09.png
    206200   :alt: Fieldset is initially collapsed
     
    214208Yet.
    215209
    216210There are two ways to solve this problem. The first is to give the ``Choice``
    217 model its own ``admin`` attribute, just as we did with ``Poll``. Here's what
     211model its own inner ``Admin`` class, just as we did with ``Poll``. Here's what
    218212that would look like::
    219213
    220     class Choice(meta.Model):
     214    class Choice(models.Model):
    221215        # ...
    222         class Meta:
    223             admin = meta.Admin()
     216        class Admin:
     217            pass
    224218
    225219Now "Choices" is an available option in the Django admin. The "Add choice" form
    226220looks like this:
     
    242236It'd be better if you could add a bunch of Choices directly when you create the
    243237Poll object. Let's make that happen.
    244238
    245 Remove the ``admin`` for the Choice model. Then, edit the ``ForeignKey(Poll)``
     239Remove the ``Admin`` for the Choice model. Then, edit the ``ForeignKey(Poll)``
    246240field like so::
    247241
    248     poll = meta.ForeignKey(Poll, edit_inline=meta.STACKED, num_in_admin=3)
     242    poll = models.ForeignKey(Poll, edit_inline=models.STACKED, num_in_admin=3)
    249243
    250244This tells Django: "Choice objects are edited on the Poll admin page. By
    251245default, provide enough fields for 3 Choices."
    252246
    253247Then change the other fields in ``Choice`` to give them ``core=True``::
    254248
    255     choice = meta.CharField(maxlength=200, core=True)
    256     votes = meta.IntegerField(core=True)
     249    choice = models.CharField(maxlength=200, core=True)
     250    votes = models.IntegerField(core=True)
    257251
    258252This tells Django: "When you edit a Choice on the Poll admin page, the 'choice'
    259253and 'votes' fields are required. The presence of at least one of them signifies
     
    277271fields for entering related Choice objects. For that reason, Django offers an
    278272alternate way of displaying inline related objects::
    279273
    280     poll = meta.ForeignKey(Poll, edit_inline=meta.TABULAR, num_in_admin=3)
     274    poll = models.ForeignKey(Poll, edit_inline=models.TABULAR, num_in_admin=3)
    281275
    282 With that ``edit_inline=meta.TABULAR`` (instead of ``meta.STACKED``), the
     276With that ``edit_inline=models.TABULAR`` (instead of ``models.STACKED``), the
    283277related objects are displayed in a more compact, table-based format:
    284278
    285279.. image:: http://media.djangoproject.com/img/doc/tutorial/admin12.png
     
    302296``list_display`` option, which is a tuple of field names to display, as columns,
    303297on the change list page for the object::
    304298
    305     class Poll(meta.Model):
     299    class Poll(models.Model):
    306300        # ...
    307         class Meta:
    308             admin = meta.Admin(
    309                 # ...
    310                 list_display = ('question', 'pub_date'),
    311             )
     301        class Admin:
     302            # ...
     303            list_display = ('question', 'pub_date')
    312304
    313305Just for good measure, let's also include the ``was_published_today`` custom
    314306method from Tutorial 1::
    315307
    316     list_display = ('question', 'pub_date', 'was_published_today'),
     308    list_display = ('question', 'pub_date', 'was_published_today')
    317309
    318310Now the poll change list page looks like this:
    319311
     
    336328Let's add another improvement to the Poll change list page: Filters. Add the
    337329following line to ``Poll.admin``::
    338330
    339     list_filter = ['pub_date'],
     331    list_filter = ['pub_date']
    340332
    341333That adds a "Filter" sidebar that lets people filter the change list by the
    342334``pub_date`` field:
     
    352344
    353345This is shaping up well. Let's add some search capability::
    354346
    355     search_fields = ['question'],
     347    search_fields = ['question']
    356348
    357349That adds a search box at the top of the change list. When somebody enters
    358350search terms, Django will search the ``question`` field. You can use as many
     
    362354Finally, because Poll objects have dates, it'd be convenient to be able to
    363355drill down by date. Add this line::
    364356
    365     date_hierarchy = 'pub_date',
     357    date_hierarchy = 'pub_date'
    366358
    367359That adds hierarchical navigation, by date, to the top of the change list page.
    368360At top level, it displays all available years. Then it drills down to months
Back to Top