Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Fixed #10776 -- Added metadata targets for the contrib.admin docs, an…

…d used one of those targets to clarify the SlugField docs. Thanks to ernop for the suggestion, and timo for the patch.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@10564 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 83623d45c754dff956a3bc90ee34e35bca8a1bce 1 parent f3c3aa2
Russell Keith-Magee authored April 16, 2009
106  docs/ref/contrib/admin/index.txt
@@ -7,6 +7,8 @@ The Django admin site
7 7
 .. module:: django.contrib.admin
8 8
    :synopsis: Django's admin site.
9 9
 
  10
+.. currentmodule:: django.contrib.admin
  11
+
10 12
 One of the most powerful parts of Django is the automatic admin interface. It
11 13
 reads metadata in your model to provide a powerful and production-ready
12 14
 interface that content producers can immediately use to start adding content to
@@ -46,7 +48,7 @@ Other topics
46 48
    :maxdepth: 1
47 49
 
48 50
    actions
49  
-   
  51
+
50 52
 .. seealso::
51 53
 
52 54
     For information about serving the media files (images, JavaScript, and CSS)
@@ -55,6 +57,8 @@ Other topics
55 57
 ``ModelAdmin`` objects
56 58
 ======================
57 59
 
  60
+.. class:: ModelAdmin
  61
+
58 62
 The ``ModelAdmin`` class is the representation of a model in the admin
59 63
 interface. These are stored in a file named ``admin.py`` in your application.
60 64
 Let's take a look at a very simple example of the ``ModelAdmin``::
@@ -90,8 +94,7 @@ subclass::
90 94
     class AuthorAdmin(admin.ModelAdmin):
91 95
         date_hierarchy = 'pub_date'
92 96
 
93  
-``date_hierarchy``
94  
-~~~~~~~~~~~~~~~~~~
  97
+.. attribute:: ModelAdmin.date_hierarchy
95 98
 
96 99
 Set ``date_hierarchy`` to the name of a ``DateField`` or ``DateTimeField`` in
97 100
 your model, and the change list page will include a date-based drilldown
@@ -101,8 +104,7 @@ Example::
101 104
 
102 105
     date_hierarchy = 'pub_date'
103 106
 
104  
-``form``
105  
-~~~~~~~~
  107
+.. attribute:: ModelAdmin.form
106 108
 
107 109
 By default a ``ModelForm`` is dynamically created for your model. It is used
108 110
 to create the form presented on both the add/change pages. You can easily
@@ -111,8 +113,7 @@ add/change pages.
111 113
 
112 114
 For an example see the section `Adding custom validation to the admin`_.
113 115
 
114  
-``fieldsets``
115  
-~~~~~~~~~~~~~
  116
+.. attribute:: ModelAdmin.fieldsets
116 117
 
117 118
 Set ``fieldsets`` to control the layout of admin "add" and "change" pages.
118 119
 
@@ -191,8 +192,7 @@ The ``field_options`` dictionary can have the following keys:
191 192
         ``django.utils.html.escape()`` to escape any HTML special
192 193
         characters.
193 194
 
194  
-``fields``
195  
-~~~~~~~~~~
  195
+.. attribute:: ModelAdmin.fields
196 196
 
197 197
 Use this option as an alternative to ``fieldsets`` if the layout does not
198 198
 matter and if you want to only show a subset of the available fields in the
@@ -211,8 +211,7 @@ displayed, sequentially, in the form.
211 211
     dictionary key that is within the ``fieldsets`` option, as described in
212 212
     the previous section.
213 213
 
214  
-``exclude``
215  
-~~~~~~~~~~~
  214
+.. attribute:: ModelAdmin.exclude
216 215
 
217 216
 This attribute, if given, should be a list of field names to exclude from the
218 217
 form.
@@ -237,22 +236,19 @@ Since the Author model only has three fields, ``name``, ``title``, and
237 236
 ``birth_date``, the forms resulting from the above declarations will contain
238 237
 exactly the same fields.
239 238
 
240  
-``filter_horizontal``
241  
-~~~~~~~~~~~~~~~~~~~~~
  239
+.. attribute:: ModelAdmin.filter_horizontal
242 240
 
243 241
 Use a nifty unobtrusive JavaScript "filter" interface instead of the
244 242
 usability-challenged ``<select multiple>`` in the admin form. The value is a
245 243
 list of fields that should be displayed as a horizontal filter interface. See
246 244
 ``filter_vertical`` to use a vertical interface.
247 245
 
248  
-``filter_vertical``
249  
-~~~~~~~~~~~~~~~~~~~
  246
+.. attribute:: ModelAdmin.filter_vertical
250 247
 
251 248
 Same as ``filter_horizontal``, but is a vertical display of the filter
252 249
 interface.
253 250
 
254  
-``list_display``
255  
-~~~~~~~~~~~~~~~~
  251
+.. attribute:: ModelAdmin.list_display
256 252
 
257 253
 Set ``list_display`` to control which fields are displayed on the change list
258 254
 page of the admin.
@@ -389,8 +385,7 @@ A few special cases to note about ``list_display``:
389 385
       The above will tell Django to order by the ``first_name`` field when
390 386
       trying to sort by ``colored_first_name`` in the admin.
391 387
 
392  
-``list_display_links``
393  
-~~~~~~~~~~~~~~~~~~~~~~
  388
+.. attribute:: ModelAdmin.list_display_links
394 389
 
395 390
 Set ``list_display_links`` to control which fields in ``list_display`` should
396 391
 be linked to the "change" page for an object.
@@ -415,8 +410,7 @@ the change list page::
415 410
 
416 411
 .. _admin-list-editable:
417 412
 
418  
-``list_editable``
419  
-~~~~~~~~~~~~~~~~~
  413
+.. attribute:: ModelAdmin.list_editable
420 414
 
421 415
 .. versionadded:: 1.1
422 416
 
@@ -441,8 +435,7 @@ edit and save multiple rows at once.
441 435
 
442 436
     You'll get a validation error if any of these rules are broken.
443 437
 
444  
-``list_filter``
445  
-~~~~~~~~~~~~~~~
  438
+.. attribute:: ModelAdmin.list_filter
446 439
 
447 440
 Set ``list_filter`` to activate filters in the right sidebar of the change list
448 441
 page of the admin. This should be a list of field names, and each specified
@@ -462,14 +455,12 @@ The above code results in an admin change list page that looks like this:
462 455
 
463 456
 (This example also has ``search_fields`` defined. See below.)
464 457
 
465  
-``list_per_page``
466  
-~~~~~~~~~~~~~~~~~
  458
+.. attribute:: ModelAdmin.list_per_page
467 459
 
468 460
 Set ``list_per_page`` to control how many items appear on each paginated admin
469 461
 change list page. By default, this is set to ``100``.
470 462
 
471  
-``list_select_related``
472  
-~~~~~~~~~~~~~~~~~~~~~~~
  463
+.. attribute:: ModelAdmin.list_select_related
473 464
 
474 465
 Set ``list_select_related`` to tell Django to use ``select_related()`` in
475 466
 retrieving the list of objects on the admin change list page. This can save you
@@ -483,13 +474,11 @@ if one of the ``list_display`` fields is a ``ForeignKey``.
483 474
 For more on ``select_related()``, see
484 475
 :ref:`the select_related() docs <select-related>`.
485 476
 
486  
-``inlines``
487  
-~~~~~~~~~~~
  477
+.. attribute:: ModelAdmin.inlines
488 478
 
489 479
 See ``InlineModelAdmin`` objects below.
490 480
 
491  
-``ordering``
492  
-~~~~~~~~~~~~
  481
+.. attribute:: ModelAdmin.ordering
493 482
 
494 483
 Set ``ordering`` to specify how objects on the admin change list page should be
495 484
 ordered. This should be a list or tuple in the same format as a model's
@@ -502,8 +491,7 @@ If this isn't provided, the Django admin will use the model's default ordering.
502 491
     Django will only honor the first element in the list/tuple; any others
503 492
     will be ignored.
504 493
 
505  
-``prepopulated_fields``
506  
-~~~~~~~~~~~~~~~~~~~~~~~
  494
+.. attribute:: ModelAdmin.prepopulated_fields
507 495
 
508 496
 Set ``prepopulated_fields`` to a dictionary mapping field names to the fields
509 497
 it should prepopulate from::
@@ -521,8 +509,7 @@ dashes for spaces).
521 509
 ``prepopulated_fields`` doesn't accept ``DateTimeField``, ``ForeignKey``, nor
522 510
 ``ManyToManyField`` fields.
523 511
 
524  
-``radio_fields``
525  
-~~~~~~~~~~~~~~~~
  512
+.. attribute:: ModelAdmin.radio_fields
526 513
 
527 514
 By default, Django's admin uses a select-box interface (<select>) for
528 515
 fields that are ``ForeignKey`` or have ``choices`` set. If a field is present
@@ -538,8 +525,7 @@ You have the choice of using ``HORIZONTAL`` or ``VERTICAL`` from the
538 525
 Don't include a field in ``radio_fields`` unless it's a ``ForeignKey`` or has
539 526
 ``choices`` set.
540 527
 
541  
-``raw_id_fields``
542  
-~~~~~~~~~~~~~~~~~
  528
+.. attribute:: ModelAdmin.raw_id_fields
543 529
 
544 530
 By default, Django's admin uses a select-box interface (<select>) for
545 531
 fields that are ``ForeignKey``. Sometimes you don't want to incur the
@@ -552,8 +538,7 @@ into a ``Input`` widget for either a ``ForeignKey`` or ``ManyToManyField``::
552 538
     class ArticleAdmin(admin.ModelAdmin):
553 539
         raw_id_fields = ("newspaper",)
554 540
 
555  
-``save_as``
556  
-~~~~~~~~~~~
  541
+.. attribute:: ModelAdmin.save_as
557 542
 
558 543
 Set ``save_as`` to enable a "save as" feature on admin change forms.
559 544
 
@@ -566,8 +551,7 @@ rather than the old object.
566 551
 
567 552
 By default, ``save_as`` is set to ``False``.
568 553
 
569  
-``save_on_top``
570  
-~~~~~~~~~~~~~~~
  554
+.. attribute:: ModelAdmin.save_on_top
571 555
 
572 556
 Set ``save_on_top`` to add save buttons across the top of your admin change
573 557
 forms.
@@ -577,8 +561,7 @@ Normally, the save buttons appear only at the bottom of the forms. If you set
577 561
 
578 562
 By default, ``save_on_top`` is set to ``False``.
579 563
 
580  
-``search_fields``
581  
-~~~~~~~~~~~~~~~~~
  564
+.. attribute:: ModelAdmin.search_fields
582 565
 
583 566
 Set ``search_fields`` to enable a search box on the admin change list page.
584 567
 This should be set to a list of field names that will be searched whenever
@@ -635,8 +618,7 @@ with an operator:
635 618
     Performs a full-text match. This is like the default search method but uses
636 619
     an index. Currently this is only available for MySQL.
637 620
 
638  
-``formfield_overrides``
639  
-~~~~~~~~~~~~~~~~~~~~~~~
  621
+.. attribute:: ModelAdmin.formfield_overrides
640 622
 
641 623
 This provides a quick-and-dirty way to override some of the
642 624
 :class:`~django.forms.Field` options for use in the admin.
@@ -676,14 +658,13 @@ The value is another dictionary; these arguments will be passed to
676 658
     that have ``raw_id_fields`` or ``radio_fields`` set. That's because
677 659
     ``raw_id_fields`` and ``radio_fields`` imply custom widgets of their own.
678 660
 
679  
-``actions``
680  
-~~~~~~~~~~~
  661
+.. attribute:: ModelAdmin.actions
681 662
 
682 663
 A list of actions to make available on the change list page. See
683 664
 :ref:`ref-contrib-admin-actions` for details.
684 665
 
685  
-``actions_on_top``, ``actions_on_bottom``
686  
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  666
+.. attribute:: ModelAdmin.actions_on_top
  667
+.. attribute:: ModelAdmin.actions_on_bottom
687 668
 
688 669
 Controls where on the page the actions bar appears. By default, the admin
689 670
 changelist displays actions at the top of the page (``actions_on_top = True;
@@ -692,8 +673,7 @@ actions_on_bottom = False``).
692 673
 ``ModelAdmin`` methods
693 674
 ----------------------
694 675
 
695  
-``save_model(self, request, obj, form, change)``
696  
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  676
+.. method:: ModelAdmin.save_model(self, request, obj, form, change)
697 677
 
698 678
 The ``save_model`` method is given the ``HttpRequest``, a model instance,
699 679
 a ``ModelForm`` instance and a boolean value based on whether it is adding or
@@ -706,8 +686,7 @@ For example to attach ``request.user`` to the object prior to saving::
706 686
             obj.user = request.user
707 687
             obj.save()
708 688
 
709  
-``save_formset(self, request, form, formset, change)``
710  
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  689
+.. method:: ModelAdmin.save_formset(self, request, form, formset, change)
711 690
 
712 691
 The ``save_formset`` method is given the ``HttpRequest``, the parent
713 692
 ``ModelForm`` instance and a boolean value based on whether it is adding or
@@ -724,8 +703,7 @@ model instance::
724 703
                 instance.save()
725 704
             formset.save_m2m()
726 705
 
727  
-``get_urls(self)``
728  
-~~~~~~~~~~~~~~~~~~~
  706
+.. method:: ModelAdmin.get_urls(self)
729 707
 
730 708
 .. versionadded:: 1.1
731 709
 
@@ -769,8 +747,7 @@ Notice the wrapped view in the fifth line above::
769 747
 
770 748
 This wrapping will protect ``self.my_view`` from unauthorized access.
771 749
 
772  
-``formfield_for_foreignkey(self, db_field, request, **kwargs)``
773  
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  750
+.. method:: ModelAdmin.formfield_for_foreignkey(self, db_field, request, **kwargs)
774 751
 
775 752
 .. versionadded:: 1.1
776 753
 
@@ -846,7 +823,7 @@ parent model. These are called inlines. Suppose you have these two models::
846 823
         author = models.ForeignKey(Author)
847 824
         title = models.CharField(max_length=100)
848 825
 
849  
-You can edit the books authored by an author on the author page. You add 
  826
+You can edit the books authored by an author on the author page. You add
850 827
 inlines to a model by specifying them in a ``ModelAdmin.inlines``::
851 828
 
852 829
     class BookInline(admin.TabularInline):
@@ -1167,7 +1144,7 @@ Linking to admin views
1167 1144
 
1168 1145
 All the admin views use :ref:`named URL patterns <naming-url-patterns>` so it's
1169 1146
 easy to link to admin views with ``urlresolvers.reverse`` or the :ttag:`url`
1170  
-template tag. 
  1147
+template tag.
1171 1148
 
1172 1149
 Each model gets its own set of views and its own name using the model's app name
1173 1150
 and model name. For example, the "add" view for a ``Choice`` model in a
@@ -1274,8 +1251,9 @@ Adding views to admin sites
1274 1251
 
1275 1252
 .. versionadded:: 1.1
1276 1253
 
1277  
-It possible to add additional views to the admin site in the same way one can
1278  
-add them to ``ModelAdmins``.  This by using the ``get_urls()`` method on an
1279  
-AdminSite in the same way as `described above`__
1280  
-
1281  
-__ `get_urls(self)`_
  1254
+Just like ``ModelAdmin``, ``AdminSite`` provides a
  1255
+:meth:`~django.contrib.admin.ModelAdmin.get_urls()` method
  1256
+that can be overridden to define additional views for the site. To add
  1257
+a new view to your admin site, extend the base
  1258
+:meth:`~django.contrib.admin.ModelAdmin.get_urls()` method to include
  1259
+a pattern for your new view.
4  docs/ref/models/fields.txt
@@ -689,6 +689,10 @@ default length of 50.
689 689
 
690 690
 Implies setting :attr:`Field.db_index` to ``True``.
691 691
 
  692
+It is often useful to automatically prepopulate a SlugField based on the value
  693
+of some other value.  You can do this automatically in the admin using
  694
+:attr:`~django.contrib.admin.ModelAdmin.prepopulated_fields`.
  695
+
692 696
 ``SmallIntegerField``
693 697
 ---------------------
694 698
 

0 notes on commit 83623d4

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