Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Fixed #15003 - assorted edits to admin docs; thanks adamv.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@15166 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 30c8a5574a73b0916b5c606ae357d14c38abe871 1 parent 614672d
Tim Graham authored January 08, 2011

Showing 1 changed file with 147 additions and 151 deletions. Show diff stats Hide diff stats

  1. 298  docs/ref/contrib/admin/index.txt
298  docs/ref/contrib/admin/index.txt
@@ -11,13 +11,6 @@ interface that content producers can immediately use to start adding content to
11 11
 the site. In this document, we discuss how to activate, use and customize
12 12
 Django's admin interface.
13 13
 
14  
-.. admonition:: Note
15  
-
16  
-    The admin site has been refactored significantly since Django 0.96. This
17  
-    document describes the newest version of the admin site, which allows for
18  
-    much richer customization. If you follow the development of Django itself,
19  
-    you may have heard this described as "newforms-admin."
20  
-
21 14
 Overview
22 15
 ========
23 16
 
@@ -26,8 +19,8 @@ There are six steps in activating the Django admin site:
26 19
     1. Add ``'django.contrib.admin'`` to your :setting:`INSTALLED_APPS`
27 20
        setting.
28 21
 
29  
-    2. Admin has two dependencies - ``django.contrib.auth`` and
30  
-       ``django.contrib.contenttypes``. If these applications are not
  22
+    2. Admin has two dependencies - :mod:`django.contrib.auth` and
  23
+       :mod:`django.contrib.contenttypes`. If these applications are not
31 24
        in your :setting:`INSTALLED_APPS` list, add them.
32 25
 
33 26
     3. Determine which of your application's models should be editable in the
@@ -87,7 +80,7 @@ Other topics
87 80
 
88 81
             admin.site.register(Author)
89 82
 
90  
-``ModelAdmin`` Options
  83
+``ModelAdmin`` options
91 84
 ----------------------
92 85
 
93 86
 The ``ModelAdmin`` is very flexible. It has several options for dealing with
@@ -97,6 +90,26 @@ subclass::
97 90
     class AuthorAdmin(admin.ModelAdmin):
98 91
         date_hierarchy = 'pub_date'
99 92
 
  93
+.. attribute:: ModelAdmin.actions
  94
+
  95
+    A list of actions to make available on the change list page. See
  96
+    :doc:`/ref/contrib/admin/actions` for details.
  97
+
  98
+.. attribute:: ModelAdmin.actions_on_top
  99
+.. attribute:: ModelAdmin.actions_on_bottom
  100
+
  101
+    Controls where on the page the actions bar appears. By default, the admin
  102
+    changelist displays actions at the top of the page (``actions_on_top = True;
  103
+    actions_on_bottom = False``).
  104
+
  105
+.. attribute:: ModelAdmin.actions_selection_counter
  106
+
  107
+    .. versionadded:: 1.2
  108
+
  109
+    Controls whether a selection counter is display next to the action dropdown.
  110
+    By default, the admin changelist will display it
  111
+    (``actions_selection_counter = True``).
  112
+
100 113
 .. attribute:: ModelAdmin.date_hierarchy
101 114
 
102 115
     Set ``date_hierarchy`` to the name of a ``DateField`` or ``DateTimeField``
@@ -109,18 +122,59 @@ subclass::
109 122
 
110 123
     .. versionadded:: 1.3
111 124
 
112  
-        This will intelligently populate itself based on available data,
113  
-        e.g. if all the dates are in one month, it'll show the day-level
114  
-        drill-down only.
  125
+    This will intelligently populate itself based on available data,
  126
+    e.g. if all the dates are in one month, it'll show the day-level
  127
+    drill-down only.
115 128
 
116  
-.. attribute:: ModelAdmin.form
  129
+.. attribute:: ModelAdmin.exclude
117 130
 
118  
-    By default a ``ModelForm`` is dynamically created for your model. It is
119  
-    used to create the form presented on both the add/change pages. You can
120  
-    easily provide your own ``ModelForm`` to override any default form behavior
121  
-    on the add/change pages.
  131
+    This attribute, if given, should be a list of field names to exclude from
  132
+    the form.
122 133
 
123  
-    For an example see the section `Adding custom validation to the admin`_.
  134
+    For example, let's consider the following model::
  135
+
  136
+        class Author(models.Model):
  137
+            name = models.CharField(max_length=100)
  138
+            title = models.CharField(max_length=3)
  139
+            birth_date = models.DateField(blank=True, null=True)
  140
+
  141
+    If you want a form for the ``Author`` model that includes only the ``name``
  142
+    and ``title`` fields, you would specify ``fields`` or ``exclude`` like
  143
+    this::
  144
+
  145
+        class AuthorAdmin(admin.ModelAdmin):
  146
+            fields = ('name', 'title')
  147
+
  148
+        class AuthorAdmin(admin.ModelAdmin):
  149
+            exclude = ('birth_date',)
  150
+
  151
+    Since the Author model only has three fields, ``name``, ``title``, and
  152
+    ``birth_date``, the forms resulting from the above declarations will
  153
+    contain exactly the same fields.
  154
+
  155
+.. attribute:: ModelAdmin.fields
  156
+
  157
+    Use this option as an alternative to ``fieldsets`` if the layout does not
  158
+    matter and if you want to only show a subset of the available fields in the
  159
+    form. For example, you could define a simpler version of the admin form for
  160
+    the ``django.contrib.flatpages.FlatPage`` model as follows::
  161
+
  162
+        class FlatPageAdmin(admin.ModelAdmin):
  163
+            fields = ('url', 'title', 'content')
  164
+
  165
+    In the above example, only the fields 'url', 'title' and 'content' will be
  166
+    displayed, sequentially, in the form.
  167
+
  168
+    .. versionadded:: 1.2
  169
+
  170
+    ``fields`` can contain values defined in :attr:`ModelAdmin.readonly_fields`
  171
+    to be displayed as read-only.
  172
+
  173
+    .. admonition:: Note
  174
+
  175
+        This ``fields`` option should not be confused with the ``fields``
  176
+        dictionary key that is within the ``fieldsets`` option, as described in
  177
+        the previous section.
124 178
 
125 179
 .. attribute:: ModelAdmin.fieldsets
126 180
 
@@ -207,67 +261,72 @@ subclass::
207 261
             ``django.utils.html.escape()`` to escape any HTML special
208 262
             characters.
209 263
 
210  
-.. attribute:: ModelAdmin.fields
211  
-
212  
-    Use this option as an alternative to ``fieldsets`` if the layout does not
213  
-    matter and if you want to only show a subset of the available fields in the
214  
-    form. For example, you could define a simpler version of the admin form for
215  
-    the ``django.contrib.flatpages.FlatPage`` model as follows::
  264
+.. attribute:: ModelAdmin.filter_horizontal
216 265
 
217  
-        class FlatPageAdmin(admin.ModelAdmin):
218  
-            fields = ('url', 'title', 'content')
  266
+    Use a nifty unobtrusive JavaScript "filter" interface instead of the
  267
+    usability-challenged ``<select multiple>`` in the admin form. The value is
  268
+    a list of fields that should be displayed as a horizontal filter interface.
  269
+    See ``filter_vertical`` to use a vertical interface.
219 270
 
220  
-    In the above example, only the fields 'url', 'title' and 'content' will be
221  
-    displayed, sequentially, in the form.
  271
+.. attribute:: ModelAdmin.filter_vertical
222 272
 
223  
-    .. versionadded:: 1.2
  273
+    Same as ``filter_horizontal``, but is a vertical display of the filter
  274
+    interface.
224 275
 
225  
-    ``fields`` can contain values defined in :attr:`ModelAdmin.readonly_fields`
226  
-    to be displayed as read-only.
  276
+.. attribute:: ModelAdmin.form
227 277
 
228  
-    .. admonition:: Note
  278
+    By default a ``ModelForm`` is dynamically created for your model. It is
  279
+    used to create the form presented on both the add/change pages. You can
  280
+    easily provide your own ``ModelForm`` to override any default form behavior
  281
+    on the add/change pages.
229 282
 
230  
-        This ``fields`` option should not be confused with the ``fields``
231  
-        dictionary key that is within the ``fieldsets`` option, as described in
232  
-        the previous section.
  283
+    For an example see the section `Adding custom validation to the admin`_.
233 284
 
234  
-.. attribute:: ModelAdmin.exclude
  285
+.. attribute:: ModelAdmin.formfield_overrides
235 286
 
236  
-    This attribute, if given, should be a list of field names to exclude from
237  
-    the form.
  287
+    This provides a quick-and-dirty way to override some of the
  288
+    :class:`~django.forms.Field` options for use in the admin.
  289
+    ``formfield_overrides`` is a dictionary mapping a field class to a dict of
  290
+    arguments to pass to the field at construction time.
238 291
 
239  
-    For example, let's consider the following model::
  292
+    Since that's a bit abstract, let's look at a concrete example. The most
  293
+    common use of ``formfield_overrides`` is to add a custom widget for a
  294
+    certain type of field. So, imagine we've written a ``RichTextEditorWidget``
  295
+    that we'd like to use for large text fields instead of the default
  296
+    ``<textarea>``. Here's how we'd do that::
240 297
 
241  
-        class Author(models.Model):
242  
-            name = models.CharField(max_length=100)
243  
-            title = models.CharField(max_length=3)
244  
-            birth_date = models.DateField(blank=True, null=True)
  298
+        from django.db import models
  299
+        from django.contrib import admin
245 300
 
246  
-    If you want a form for the ``Author`` model that includes only the ``name``
247  
-    and ``title`` fields, you would specify ``fields`` or ``exclude`` like
248  
-    this::
  301
+        # Import our custom widget and our model from where they're defined
  302
+        from myapp.widgets import RichTextEditorWidget
  303
+        from myapp.models import MyModel
249 304
 
250  
-        class AuthorAdmin(admin.ModelAdmin):
251  
-            fields = ('name', 'title')
  305
+        class MyModelAdmin(admin.ModelAdmin):
  306
+            formfield_overrides = {
  307
+                models.TextField: {'widget': RichTextEditorWidget},
  308
+            }
252 309
 
253  
-        class AuthorAdmin(admin.ModelAdmin):
254  
-            exclude = ('birth_date',)
  310
+    Note that the key in the dictionary is the actual field class, *not* a
  311
+    string. The value is another dictionary; these arguments will be passed to
  312
+    :meth:`~django.forms.Field.__init__`. See :doc:`/ref/forms/api` for
  313
+    details.
255 314
 
256  
-    Since the Author model only has three fields, ``name``, ``title``, and
257  
-    ``birth_date``, the forms resulting from the above declarations will
258  
-    contain exactly the same fields.
  315
+    .. warning::
259 316
 
260  
-.. attribute:: ModelAdmin.filter_horizontal
  317
+        If you want to use a custom widget with a relation field (i.e.
  318
+        :class:`~django.db.models.ForeignKey` or
  319
+        :class:`~django.db.models.ManyToManyField`), make sure you haven't
  320
+        included that field's name in ``raw_id_fields`` or ``radio_fields``.
261 321
 
262  
-    Use a nifty unobtrusive JavaScript "filter" interface instead of the
263  
-    usability-challenged ``<select multiple>`` in the admin form. The value is
264  
-    a list of fields that should be displayed as a horizontal filter interface.
265  
-    See ``filter_vertical`` to use a vertical interface.
  322
+        ``formfield_overrides`` won't let you change the widget on relation
  323
+        fields that have ``raw_id_fields`` or ``radio_fields`` set. That's
  324
+        because ``raw_id_fields`` and ``radio_fields`` imply custom widgets of
  325
+        their own.
266 326
 
267  
-.. attribute:: ModelAdmin.filter_vertical
  327
+.. attribute:: ModelAdmin.inlines
268 328
 
269  
-    Same as ``filter_horizontal``, but is a vertical display of the filter
270  
-    interface.
  329
+    See :class:`InlineModelAdmin` objects below.
271 330
 
272 331
 .. attribute:: ModelAdmin.list_display
273 332
 
@@ -496,15 +555,11 @@ subclass::
496 555
     regardless of this setting if one of the ``list_display`` fields is a
497 556
     ``ForeignKey``.
498 557
 
499  
-.. attribute:: ModelAdmin.inlines
500  
-
501  
-    See :class:`InlineModelAdmin` objects below.
502  
-
503 558
 .. attribute:: ModelAdmin.ordering
504 559
 
505 560
     Set ``ordering`` to specify how lists of objects should be ordered in the
506 561
     Django admin views. This should be a list or tuple in the same format as a
507  
-    model's ``ordering`` parameter.
  562
+    model's :attr:`~django.db.models.Options.ordering` parameter.
508 563
 
509 564
     If this isn't provided, the Django admin will use the model's default
510 565
     ordering.
@@ -674,68 +729,6 @@ subclass::
674 729
         Performs a full-text match. This is like the default search method but
675 730
         uses an index. Currently this is only available for MySQL.
676 731
 
677  
-.. attribute:: ModelAdmin.formfield_overrides
678  
-
679  
-    This provides a quick-and-dirty way to override some of the
680  
-    :class:`~django.forms.Field` options for use in the admin.
681  
-    ``formfield_overrides`` is a dictionary mapping a field class to a dict of
682  
-    arguments to pass to the field at construction time.
683  
-
684  
-    Since that's a bit abstract, let's look at a concrete example. The most
685  
-    common use of ``formfield_overrides`` is to add a custom widget for a
686  
-    certain type of field. So, imagine we've written a ``RichTextEditorWidget``
687  
-    that we'd like to use for large text fields instead of the default
688  
-    ``<textarea>``. Here's how we'd do that::
689  
-
690  
-        from django.db import models
691  
-        from django.contrib import admin
692  
-
693  
-        # Import our custom widget and our model from where they're defined
694  
-        from myapp.widgets import RichTextEditorWidget
695  
-        from myapp.models import MyModel
696  
-
697  
-        class MyModelAdmin(admin.ModelAdmin):
698  
-            formfield_overrides = {
699  
-                models.TextField: {'widget': RichTextEditorWidget},
700  
-            }
701  
-
702  
-    Note that the key in the dictionary is the actual field class, *not* a
703  
-    string. The value is another dictionary; these arguments will be passed to
704  
-    :meth:`~django.forms.Field.__init__`. See :doc:`/ref/forms/api` for
705  
-    details.
706  
-
707  
-    .. warning::
708  
-
709  
-        If you want to use a custom widget with a relation field (i.e.
710  
-        :class:`~django.db.models.ForeignKey` or
711  
-        :class:`~django.db.models.ManyToManyField`), make sure you haven't
712  
-        included that field's name in ``raw_id_fields`` or ``radio_fields``.
713  
-
714  
-        ``formfield_overrides`` won't let you change the widget on relation
715  
-        fields that have ``raw_id_fields`` or ``radio_fields`` set. That's
716  
-        because ``raw_id_fields`` and ``radio_fields`` imply custom widgets of
717  
-        their own.
718  
-
719  
-.. attribute:: ModelAdmin.actions
720  
-
721  
-    A list of actions to make available on the change list page. See
722  
-    :doc:`/ref/contrib/admin/actions` for details.
723  
-
724  
-.. attribute:: ModelAdmin.actions_on_top
725  
-.. attribute:: ModelAdmin.actions_on_bottom
726  
-
727  
-    Controls where on the page the actions bar appears. By default, the admin
728  
-    changelist displays actions at the top of the page (``actions_on_top = True;
729  
-    actions_on_bottom = False``).
730  
-
731  
-.. attribute:: ModelAdmin.actions_selection_counter
732  
-
733  
-    .. versionadded:: 1.2
734  
-
735  
-    Controls whether a selection counter is display next to the action dropdown.
736  
-    By default, the admin changelist will display it
737  
-    (``actions_selection_counter = True``).
738  
-
739 732
 Custom template options
740 733
 ~~~~~~~~~~~~~~~~~~~~~~~
741 734
 
@@ -1043,8 +1036,8 @@ on your ``ModelAdmin``::
1043 1036
             }
1044 1037
             js = ("my_code.js",)
1045 1038
 
1046  
-Keep in mind that this will be prepended with ``MEDIA_URL``. The same rules
1047  
-apply as :doc:`regular media definitions on forms </topics/forms/media>`.
  1039
+Keep in mind that this will be prepended with :setting:`MEDIA_URL`. The same
  1040
+rules apply as :doc:`regular media definitions on forms </topics/forms/media>`.
1048 1041
 
1049 1042
 Django admin Javascript makes use of the `jQuery`_ library. To avoid
1050 1043
 conflict with user scripts, Django's jQuery is namespaced as
@@ -1255,17 +1248,18 @@ automatically::
1255 1248
             FriendshipInline,
1256 1249
         ]
1257 1250
 
1258  
-Working with Many-to-Many Models
  1251
+Working with many-to-many models
1259 1252
 --------------------------------
1260 1253
 
1261 1254
 .. versionadded:: 1.2
1262 1255
 
1263 1256
 By default, admin widgets for many-to-many relations will be displayed
1264  
-on whichever model contains the actual reference to the ``ManyToManyField``.
1265  
-Depending on your ``ModelAdmin`` definition, each many-to-many field in your
1266  
-model will be represented by a standard HTML ``<select multiple>``, a
1267  
-horizontal or vertical filter, or a ``raw_id_admin`` widget. However, it is
1268  
-also possible to to replace these widgets with inlines.
  1257
+on whichever model contains the actual reference to the
  1258
+:class:`~django.db.models.ManyToManyField`. Depending on your ``ModelAdmin``
  1259
+definition, each many-to-many field in your model will be represented by a
  1260
+standard HTML ``<select multiple>``, a horizontal or vertical filter, or a
  1261
+``raw_id_admin`` widget. However, it is also possible to to replace these
  1262
+widgets with inlines.
1269 1263
 
1270 1264
 Suppose we have the following models::
1271 1265
 
@@ -1311,14 +1305,15 @@ In all other respects, the ``InlineModelAdmin`` is exactly the same as any
1311 1305
 other. You can customize the appearance using any of the normal
1312 1306
 ``ModelAdmin`` properties.
1313 1307
 
1314  
-Working with Many-to-Many Intermediary Models
1315  
-----------------------------------------------
  1308
+Working with many-to-many intermediary models
  1309
+---------------------------------------------
1316 1310
 
1317 1311
 When you specify an intermediary model using the ``through`` argument to a
1318  
-``ManyToManyField``, the admin will not display a widget by default. This is
1319  
-because each instance of that intermediary model requires more information
1320  
-than could be displayed in a single widget, and the layout required for
1321  
-multiple widgets will vary depending on the intermediate model.
  1312
+:class:`~django.db.models.ManyToManyField`, the admin will not display a
  1313
+widget by default. This is because each instance of that intermediary model
  1314
+requires more information than could be displayed in a single widget, and the
  1315
+layout required for multiple widgets will vary depending on the intermediate
  1316
+model.
1322 1317
 
1323 1318
 However, we still want to be able to edit that information inline. Fortunately,
1324 1319
 this is easy to do with inline admin models. Suppose we have the following
@@ -1407,7 +1402,7 @@ other inline. In your ``admin.py`` for this example app::
1407 1402
 See the :doc:`contenttypes documentation </ref/contrib/contenttypes>` for more
1408 1403
 specific information.
1409 1404
 
1410  
-Overriding Admin Templates
  1405
+Overriding admin templates
1411 1406
 ==========================
1412 1407
 
1413 1408
 It is relatively easy to override many of the templates which the admin module
@@ -1422,7 +1417,7 @@ directory.
1422 1417
 
1423 1418
 In order to override one or more of them, first create an ``admin`` directory
1424 1419
 in your project's ``templates`` directory. This can be any of the directories
1425  
-you specified in ``TEMPLATE_DIRS``.
  1420
+you specified in :setting:`TEMPLATE_DIRS`.
1426 1421
 
1427 1422
 Within this ``admin`` directory, create sub-directories named after your app.
1428 1423
 Within these app subdirectories create sub-directories named after your models.
@@ -1548,10 +1543,10 @@ Templates can override or extend base admin templates as described in
1548 1543
 
1549 1544
     Path to a custom template that will be used by the admin site login view.
1550 1545
 
1551  
-.. versionadded:: 1.3
1552  
-
1553 1546
 .. attribute:: AdminSite.login_form
1554 1547
 
  1548
+    .. versionadded:: 1.3
  1549
+
1555 1550
     Subclass of :class:`~django.contrib.auth.forms.AuthenticationForm` that
1556 1551
     will be used by the admin site login view.
1557 1552
 
@@ -1652,13 +1647,14 @@ a pattern for your new view.
1652 1647
 .. note::
1653 1648
     Any view you render that uses the admin templates, or extends the base
1654 1649
     admin template, should provide the ``current_app`` argument to
1655  
-    ``RequestContext`` or ``Context`` when rendering the template.  It should
1656  
-    be set to either ``self.name`` if your view is on an ``AdminSite`` or
1657  
-    ``self.admin_site.name`` if your view is on a ``ModelAdmin``.
  1650
+    :class:`~django.template.RequestContext` or :class:`~django.template.Context`
  1651
+    when rendering the template.  It should be set to either ``self.name`` if
  1652
+    your view is on an ``AdminSite`` or ``self.admin_site.name`` if your view
  1653
+    is on a ``ModelAdmin``.
1658 1654
 
1659 1655
 .. _admin-reverse-urls:
1660 1656
 
1661  
-Reversing Admin URLs
  1657
+Reversing admin URLs
1662 1658
 ====================
1663 1659
 
1664 1660
 When an :class:`AdminSite` is deployed, the views provided by that site are

0 notes on commit 30c8a55

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