From 30c8a5574a73b0916b5c606ae357d14c38abe871 Mon Sep 17 00:00:00 2001
From: Timo Graham <timograham@gmail.com>
Date: Sat, 8 Jan 2011 21:15:00 +0000
Subject: [PATCH] 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
---
docs/ref/contrib/admin/index.txt | 312 +++++++++++++++----------------
1 file changed, 154 insertions(+), 158 deletions(-)
diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt
index 326bca4d18..ca7609cf80 100644
--- a/docs/ref/contrib/admin/index.txt
+++ b/docs/ref/contrib/admin/index.txt
@@ -11,13 +11,6 @@ interface that content producers can immediately use to start adding content to
the site. In this document, we discuss how to activate, use and customize
Django's admin interface.
-.. admonition:: Note
-
- The admin site has been refactored significantly since Django 0.96. This
- document describes the newest version of the admin site, which allows for
- much richer customization. If you follow the development of Django itself,
- you may have heard this described as "newforms-admin."
-
Overview
========
@@ -26,8 +19,8 @@ There are six steps in activating the Django admin site:
1. Add ``'django.contrib.admin'`` to your :setting:`INSTALLED_APPS`
setting.
- 2. Admin has two dependencies - ``django.contrib.auth`` and
- ``django.contrib.contenttypes``. If these applications are not
+ 2. Admin has two dependencies - :mod:`django.contrib.auth` and
+ :mod:`django.contrib.contenttypes`. If these applications are not
in your :setting:`INSTALLED_APPS` list, add them.
3. Determine which of your application's models should be editable in the
@@ -87,7 +80,7 @@ Other topics
admin.site.register(Author)
-``ModelAdmin`` Options
+``ModelAdmin`` options
----------------------
The ``ModelAdmin`` is very flexible. It has several options for dealing with
@@ -97,6 +90,26 @@ subclass::
class AuthorAdmin(admin.ModelAdmin):
date_hierarchy = 'pub_date'
+.. attribute:: ModelAdmin.actions
+
+ A list of actions to make available on the change list page. See
+ :doc:`/ref/contrib/admin/actions` for details.
+
+.. attribute:: ModelAdmin.actions_on_top
+.. attribute:: ModelAdmin.actions_on_bottom
+
+ Controls where on the page the actions bar appears. By default, the admin
+ changelist displays actions at the top of the page (``actions_on_top = True;
+ actions_on_bottom = False``).
+
+.. attribute:: ModelAdmin.actions_selection_counter
+
+ .. versionadded:: 1.2
+
+ Controls whether a selection counter is display next to the action dropdown.
+ By default, the admin changelist will display it
+ (``actions_selection_counter = True``).
+
.. attribute:: ModelAdmin.date_hierarchy
Set ``date_hierarchy`` to the name of a ``DateField`` or ``DateTimeField``
@@ -109,18 +122,59 @@ subclass::
.. versionadded:: 1.3
- This will intelligently populate itself based on available data,
- e.g. if all the dates are in one month, it'll show the day-level
- drill-down only.
+ This will intelligently populate itself based on available data,
+ e.g. if all the dates are in one month, it'll show the day-level
+ drill-down only.
-.. attribute:: ModelAdmin.form
+.. attribute:: ModelAdmin.exclude
- By default a ``ModelForm`` is dynamically created for your model. It is
- used to create the form presented on both the add/change pages. You can
- easily provide your own ``ModelForm`` to override any default form behavior
- on the add/change pages.
+ This attribute, if given, should be a list of field names to exclude from
+ the form.
- For an example see the section `Adding custom validation to the admin`_.
+ For example, let's consider the following model::
+
+ class Author(models.Model):
+ name = models.CharField(max_length=100)
+ title = models.CharField(max_length=3)
+ birth_date = models.DateField(blank=True, null=True)
+
+ If you want a form for the ``Author`` model that includes only the ``name``
+ and ``title`` fields, you would specify ``fields`` or ``exclude`` like
+ this::
+
+ class AuthorAdmin(admin.ModelAdmin):
+ fields = ('name', 'title')
+
+ class AuthorAdmin(admin.ModelAdmin):
+ exclude = ('birth_date',)
+
+ Since the Author model only has three fields, ``name``, ``title``, and
+ ``birth_date``, the forms resulting from the above declarations will
+ contain exactly the same fields.
+
+.. attribute:: ModelAdmin.fields
+
+ Use this option as an alternative to ``fieldsets`` if the layout does not
+ matter and if you want to only show a subset of the available fields in the
+ form. For example, you could define a simpler version of the admin form for
+ the ``django.contrib.flatpages.FlatPage`` model as follows::
+
+ class FlatPageAdmin(admin.ModelAdmin):
+ fields = ('url', 'title', 'content')
+
+ In the above example, only the fields 'url', 'title' and 'content' will be
+ displayed, sequentially, in the form.
+
+ .. versionadded:: 1.2
+
+ ``fields`` can contain values defined in :attr:`ModelAdmin.readonly_fields`
+ to be displayed as read-only.
+
+ .. admonition:: Note
+
+ This ``fields`` option should not be confused with the ``fields``
+ dictionary key that is within the ``fieldsets`` option, as described in
+ the previous section.
.. attribute:: ModelAdmin.fieldsets
@@ -207,56 +261,6 @@ subclass::
``django.utils.html.escape()`` to escape any HTML special
characters.
-.. attribute:: ModelAdmin.fields
-
- Use this option as an alternative to ``fieldsets`` if the layout does not
- matter and if you want to only show a subset of the available fields in the
- form. For example, you could define a simpler version of the admin form for
- the ``django.contrib.flatpages.FlatPage`` model as follows::
-
- class FlatPageAdmin(admin.ModelAdmin):
- fields = ('url', 'title', 'content')
-
- In the above example, only the fields 'url', 'title' and 'content' will be
- displayed, sequentially, in the form.
-
- .. versionadded:: 1.2
-
- ``fields`` can contain values defined in :attr:`ModelAdmin.readonly_fields`
- to be displayed as read-only.
-
- .. admonition:: Note
-
- This ``fields`` option should not be confused with the ``fields``
- dictionary key that is within the ``fieldsets`` option, as described in
- the previous section.
-
-.. attribute:: ModelAdmin.exclude
-
- This attribute, if given, should be a list of field names to exclude from
- the form.
-
- For example, let's consider the following model::
-
- class Author(models.Model):
- name = models.CharField(max_length=100)
- title = models.CharField(max_length=3)
- birth_date = models.DateField(blank=True, null=True)
-
- If you want a form for the ``Author`` model that includes only the ``name``
- and ``title`` fields, you would specify ``fields`` or ``exclude`` like
- this::
-
- class AuthorAdmin(admin.ModelAdmin):
- fields = ('name', 'title')
-
- class AuthorAdmin(admin.ModelAdmin):
- exclude = ('birth_date',)
-
- Since the Author model only has three fields, ``name``, ``title``, and
- ``birth_date``, the forms resulting from the above declarations will
- contain exactly the same fields.
-
.. attribute:: ModelAdmin.filter_horizontal
Use a nifty unobtrusive JavaScript "filter" interface instead of the
@@ -269,6 +273,61 @@ subclass::
Same as ``filter_horizontal``, but is a vertical display of the filter
interface.
+.. attribute:: ModelAdmin.form
+
+ By default a ``ModelForm`` is dynamically created for your model. It is
+ used to create the form presented on both the add/change pages. You can
+ easily provide your own ``ModelForm`` to override any default form behavior
+ on the add/change pages.
+
+ For an example see the section `Adding custom validation to the admin`_.
+
+.. attribute:: ModelAdmin.formfield_overrides
+
+ This provides a quick-and-dirty way to override some of the
+ :class:`~django.forms.Field` options for use in the admin.
+ ``formfield_overrides`` is a dictionary mapping a field class to a dict of
+ arguments to pass to the field at construction time.
+
+ Since that's a bit abstract, let's look at a concrete example. The most
+ common use of ``formfield_overrides`` is to add a custom widget for a
+ certain type of field. So, imagine we've written a ``RichTextEditorWidget``
+ that we'd like to use for large text fields instead of the default
+ ``<textarea>``. Here's how we'd do that::
+
+ from django.db import models
+ from django.contrib import admin
+
+ # Import our custom widget and our model from where they're defined
+ from myapp.widgets import RichTextEditorWidget
+ from myapp.models import MyModel
+
+ class MyModelAdmin(admin.ModelAdmin):
+ formfield_overrides = {
+ models.TextField: {'widget': RichTextEditorWidget},
+ }
+
+ Note that the key in the dictionary is the actual field class, *not* a
+ string. The value is another dictionary; these arguments will be passed to
+ :meth:`~django.forms.Field.__init__`. See :doc:`/ref/forms/api` for
+ details.
+
+ .. warning::
+
+ If you want to use a custom widget with a relation field (i.e.
+ :class:`~django.db.models.ForeignKey` or
+ :class:`~django.db.models.ManyToManyField`), make sure you haven't
+ included that field's name in ``raw_id_fields`` or ``radio_fields``.
+
+ ``formfield_overrides`` won't let you change the widget on relation
+ fields that have ``raw_id_fields`` or ``radio_fields`` set. That's
+ because ``raw_id_fields`` and ``radio_fields`` imply custom widgets of
+ their own.
+
+.. attribute:: ModelAdmin.inlines
+
+ See :class:`InlineModelAdmin` objects below.
+
.. attribute:: ModelAdmin.list_display
Set ``list_display`` to control which fields are displayed on the change
@@ -496,15 +555,11 @@ subclass::
regardless of this setting if one of the ``list_display`` fields is a
``ForeignKey``.
-.. attribute:: ModelAdmin.inlines
-
- See :class:`InlineModelAdmin` objects below.
-
.. attribute:: ModelAdmin.ordering
Set ``ordering`` to specify how lists of objects should be ordered in the
Django admin views. This should be a list or tuple in the same format as a
- model's ``ordering`` parameter.
+ model's :attr:`~django.db.models.Options.ordering` parameter.
If this isn't provided, the Django admin will use the model's default
ordering.
@@ -674,68 +729,6 @@ subclass::
Performs a full-text match. This is like the default search method but
uses an index. Currently this is only available for MySQL.
-.. attribute:: ModelAdmin.formfield_overrides
-
- This provides a quick-and-dirty way to override some of the
- :class:`~django.forms.Field` options for use in the admin.
- ``formfield_overrides`` is a dictionary mapping a field class to a dict of
- arguments to pass to the field at construction time.
-
- Since that's a bit abstract, let's look at a concrete example. The most
- common use of ``formfield_overrides`` is to add a custom widget for a
- certain type of field. So, imagine we've written a ``RichTextEditorWidget``
- that we'd like to use for large text fields instead of the default
- ``<textarea>``. Here's how we'd do that::
-
- from django.db import models
- from django.contrib import admin
-
- # Import our custom widget and our model from where they're defined
- from myapp.widgets import RichTextEditorWidget
- from myapp.models import MyModel
-
- class MyModelAdmin(admin.ModelAdmin):
- formfield_overrides = {
- models.TextField: {'widget': RichTextEditorWidget},
- }
-
- Note that the key in the dictionary is the actual field class, *not* a
- string. The value is another dictionary; these arguments will be passed to
- :meth:`~django.forms.Field.__init__`. See :doc:`/ref/forms/api` for
- details.
-
- .. warning::
-
- If you want to use a custom widget with a relation field (i.e.
- :class:`~django.db.models.ForeignKey` or
- :class:`~django.db.models.ManyToManyField`), make sure you haven't
- included that field's name in ``raw_id_fields`` or ``radio_fields``.
-
- ``formfield_overrides`` won't let you change the widget on relation
- fields that have ``raw_id_fields`` or ``radio_fields`` set. That's
- because ``raw_id_fields`` and ``radio_fields`` imply custom widgets of
- their own.
-
-.. attribute:: ModelAdmin.actions
-
- A list of actions to make available on the change list page. See
- :doc:`/ref/contrib/admin/actions` for details.
-
-.. attribute:: ModelAdmin.actions_on_top
-.. attribute:: ModelAdmin.actions_on_bottom
-
- Controls where on the page the actions bar appears. By default, the admin
- changelist displays actions at the top of the page (``actions_on_top = True;
- actions_on_bottom = False``).
-
-.. attribute:: ModelAdmin.actions_selection_counter
-
- .. versionadded:: 1.2
-
- Controls whether a selection counter is display next to the action dropdown.
- By default, the admin changelist will display it
- (``actions_selection_counter = True``).
-
Custom template options
~~~~~~~~~~~~~~~~~~~~~~~
@@ -1043,8 +1036,8 @@ on your ``ModelAdmin``::
}
js = ("my_code.js",)
-Keep in mind that this will be prepended with ``MEDIA_URL``. The same rules
-apply as :doc:`regular media definitions on forms </topics/forms/media>`.
+Keep in mind that this will be prepended with :setting:`MEDIA_URL`. The same
+rules apply as :doc:`regular media definitions on forms </topics/forms/media>`.
Django admin Javascript makes use of the `jQuery`_ library. To avoid
conflict with user scripts, Django's jQuery is namespaced as
@@ -1255,17 +1248,18 @@ automatically::
FriendshipInline,
]
-Working with Many-to-Many Models
+Working with many-to-many models
--------------------------------
.. versionadded:: 1.2
By default, admin widgets for many-to-many relations will be displayed
-on whichever model contains the actual reference to the ``ManyToManyField``.
-Depending on your ``ModelAdmin`` definition, each many-to-many field in your
-model will be represented by a standard HTML ``<select multiple>``, a
-horizontal or vertical filter, or a ``raw_id_admin`` widget. However, it is
-also possible to to replace these widgets with inlines.
+on whichever model contains the actual reference to the
+:class:`~django.db.models.ManyToManyField`. Depending on your ``ModelAdmin``
+definition, each many-to-many field in your model will be represented by a
+standard HTML ``<select multiple>``, a horizontal or vertical filter, or a
+``raw_id_admin`` widget. However, it is also possible to to replace these
+widgets with inlines.
Suppose we have the following models::
@@ -1311,14 +1305,15 @@ In all other respects, the ``InlineModelAdmin`` is exactly the same as any
other. You can customize the appearance using any of the normal
``ModelAdmin`` properties.
-Working with Many-to-Many Intermediary Models
-----------------------------------------------
+Working with many-to-many intermediary models
+---------------------------------------------
When you specify an intermediary model using the ``through`` argument to a
-``ManyToManyField``, the admin will not display a widget by default. This is
-because each instance of that intermediary model requires more information
-than could be displayed in a single widget, and the layout required for
-multiple widgets will vary depending on the intermediate model.
+:class:`~django.db.models.ManyToManyField`, the admin will not display a
+widget by default. This is because each instance of that intermediary model
+requires more information than could be displayed in a single widget, and the
+layout required for multiple widgets will vary depending on the intermediate
+model.
However, we still want to be able to edit that information inline. Fortunately,
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::
See the :doc:`contenttypes documentation </ref/contrib/contenttypes>` for more
specific information.
-Overriding Admin Templates
+Overriding admin templates
==========================
It is relatively easy to override many of the templates which the admin module
@@ -1422,7 +1417,7 @@ directory.
In order to override one or more of them, first create an ``admin`` directory
in your project's ``templates`` directory. This can be any of the directories
-you specified in ``TEMPLATE_DIRS``.
+you specified in :setting:`TEMPLATE_DIRS`.
Within this ``admin`` directory, create sub-directories named after your app.
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
Path to a custom template that will be used by the admin site login view.
-.. versionadded:: 1.3
-
.. attribute:: AdminSite.login_form
+ .. versionadded:: 1.3
+
Subclass of :class:`~django.contrib.auth.forms.AuthenticationForm` that
will be used by the admin site login view.
@@ -1652,13 +1647,14 @@ a pattern for your new view.
.. note::
Any view you render that uses the admin templates, or extends the base
admin template, should provide the ``current_app`` argument to
- ``RequestContext`` or ``Context`` when rendering the template. It should
- be set to either ``self.name`` if your view is on an ``AdminSite`` or
- ``self.admin_site.name`` if your view is on a ``ModelAdmin``.
+ :class:`~django.template.RequestContext` or :class:`~django.template.Context`
+ when rendering the template. It should be set to either ``self.name`` if
+ your view is on an ``AdminSite`` or ``self.admin_site.name`` if your view
+ is on a ``ModelAdmin``.
.. _admin-reverse-urls:
-Reversing Admin URLs
+Reversing admin URLs
====================
When an :class:`AdminSite` is deployed, the views provided by that site are