Browse files

[1.0.X] Fixed #10776 -- Added metadata targets for the contrib.admin …

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

Merge of r10564 from trunk.

git-svn-id: bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
freakboy3742 committed Apr 16, 2009
1 parent c89bf43 commit e249b0ec4d8bb3880883927a1c732d882bcdfa48
Showing with 32 additions and 46 deletions.
  1. +28 −46 docs/ref/contrib/admin.txt
  2. +4 −0 docs/ref/models/fields.txt
@@ -7,6 +7,8 @@ The Django admin site
.. module:: django.contrib.admin
:synopsis: Django's admin site.
+.. currentmodule:: django.contrib.admin
One of the most powerful parts of Django is the automatic admin interface. It
reads metadata in your model to provide a powerful and production-ready
interface that content producers can immediately use to start adding content to
@@ -38,7 +40,7 @@ There are five steps in activating the Django admin site:
``ModelAdmin`` classes.
5. Hook the ``AdminSite`` instance into your URLconf.
.. seealso::
For information about serving the media files (images, JavaScript, and CSS)
@@ -47,6 +49,8 @@ There are five steps in activating the Django admin site:
``ModelAdmin`` objects
+.. class:: ModelAdmin
The ``ModelAdmin`` class is the representation of a model in the admin
interface. These are stored in a file named ```` in your application.
Let's take a look at a very simple example of the ``ModelAdmin``::
@@ -82,8 +86,7 @@ subclass::
class AuthorAdmin(admin.ModelAdmin):
date_hierarchy = 'pub_date'
+.. attribute:: ModelAdmin.date_hierarchy
Set ``date_hierarchy`` to the name of a ``DateField`` or ``DateTimeField`` in
your model, and the change list page will include a date-based drilldown
@@ -93,8 +96,7 @@ Example::
date_hierarchy = 'pub_date'
+.. 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
@@ -103,8 +105,7 @@ add/change pages.
For an example see the section `Adding custom validation to the admin`_.
+.. attribute:: ModelAdmin.fieldsets
Set ``fieldsets`` to control the layout of admin "add" and "change" pages.
@@ -183,8 +184,7 @@ The ``field_options`` dictionary can have the following keys:
``django.utils.html.escape()`` to escape any HTML special
+.. 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
@@ -203,8 +203,7 @@ displayed, sequentially, in the form.
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
@@ -229,22 +228,19 @@ 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
usability-challenged ``<select multiple>`` in the admin form. The value is a
list of fields that should be displayed as a horizontal filter interface. See
``filter_vertical`` to use a vertical interface.
+.. attribute:: ModelAdmin.filter_vertical
Same as ``filter_horizontal``, but is a vertical display of the filter
+.. attribute:: ModelAdmin.list_display
Set ``list_display`` to control which fields are displayed on the change list
page of the admin.
@@ -381,8 +377,7 @@ A few special cases to note about ``list_display``:
The above will tell Django to order by the ``first_name`` field when
trying to sort by ``colored_first_name`` in the admin.
+.. attribute:: ModelAdmin.list_display_links
Set ``list_display_links`` to control which fields in ``list_display`` should
be linked to the "change" page for an object.
@@ -405,8 +400,7 @@ the change list page::
list_display = ('first_name', 'last_name', 'birthday')
list_display_links = ('first_name', 'last_name')
+.. attribute:: ModelAdmin.list_filter
Set ``list_filter`` to activate filters in the right sidebar of the change list
page of the admin. This should be a list of field names, and each specified
@@ -426,14 +420,12 @@ The above code results in an admin change list page that looks like this:
(This example also has ``search_fields`` defined. See below.)
+.. attribute:: ModelAdmin.list_per_page
Set ``list_per_page`` to control how many items appear on each paginated admin
change list page. By default, this is set to ``100``.
+.. attribute:: ModelAdmin.list_select_related
Set ``list_select_related`` to tell Django to use ``select_related()`` in
retrieving the list of objects on the admin change list page. This can save you
@@ -447,13 +439,11 @@ if one of the ``list_display`` fields is a ``ForeignKey``.
For more on ``select_related()``, see
:ref:`the select_related() docs <select-related>`.
+.. attribute:: ModelAdmin.inlines
See ``InlineModelAdmin`` objects below.
+.. attribute:: ModelAdmin.ordering
Set ``ordering`` to specify how objects on the admin change list page should be
ordered. This should be a list or tuple in the same format as a model's
@@ -466,8 +456,7 @@ If this isn't provided, the Django admin will use the model's default ordering.
Django will only honor the first element in the list/tuple; any others
will be ignored.
+.. attribute:: ModelAdmin.prepopulated_fields
Set ``prepopulated_fields`` to a dictionary mapping field names to the fields
it should prepopulate from::
@@ -485,8 +474,7 @@ dashes for spaces).
``prepopulated_fields`` doesn't accept ``DateTimeField``, ``ForeignKey``, nor
``ManyToManyField`` fields.
+.. attribute:: ModelAdmin.radio_fields
By default, Django's admin uses a select-box interface (<select>) for
fields that are ``ForeignKey`` or have ``choices`` set. If a field is present
@@ -502,8 +490,7 @@ You have the choice of using ``HORIZONTAL`` or ``VERTICAL`` from the
Don't include a field in ``radio_fields`` unless it's a ``ForeignKey`` or has
``choices`` set.
+.. attribute:: ModelAdmin.raw_id_fields
By default, Django's admin uses a select-box interface (<select>) for
fields that are ``ForeignKey``. Sometimes you don't want to incur the
@@ -516,8 +503,7 @@ into a ``Input`` widget for either a ``ForeignKey`` or ``ManyToManyField``::
class ArticleAdmin(admin.ModelAdmin):
raw_id_fields = ("newspaper",)
+.. attribute:: ModelAdmin.save_as
Set ``save_as`` to enable a "save as" feature on admin change forms.
@@ -530,8 +516,7 @@ rather than the old object.
By default, ``save_as`` is set to ``False``.
+.. attribute:: ModelAdmin.save_on_top
Set ``save_on_top`` to add save buttons across the top of your admin change
@@ -541,8 +526,7 @@ Normally, the save buttons appear only at the bottom of the forms. If you set
By default, ``save_on_top`` is set to ``False``.
+.. attribute:: ModelAdmin.search_fields
Set ``search_fields`` to enable a search box on the admin change list page.
This should be set to a list of field names that will be searched whenever
@@ -602,8 +586,7 @@ with an operator:
``ModelAdmin`` methods
-``save_model(self, request, obj, form, change)``
+.. method:: ModelAdmin.save_model(self, request, obj, form, change)
The ``save_model`` method is given the ``HttpRequest``, a model instance,
a ``ModelForm`` instance and a boolean value based on whether it is adding or
@@ -616,8 +599,7 @@ For example to attach ``request.user`` to the object prior to saving::
obj.user = request.user
-``save_formset(self, request, form, formset, change)``
+.. method:: ModelAdmin.save_formset(self, request, form, formset, change)
The ``save_formset`` method is given the ``HttpRequest``, the parent
``ModelForm`` instance and a boolean value based on whether it is adding or
@@ -692,7 +674,7 @@ parent model. These are called inlines. Suppose you have these two models::
author = models.ForeignKey(Author)
title = models.CharField(max_length=100)
-You can edit the books authored by an author on the author page. You add
+You can edit the books authored by an author on the author page. You add
inlines to a model by specifying them in a ``ModelAdmin.inlines``::
class BookInline(admin.TabularInline):
@@ -689,6 +689,10 @@ default length of 50.
Implies setting :attr:`Field.db_index` to ``True``.
+It is often useful to automatically prepopulate a SlugField based on the value
+of some other value. You can do this automatically in the admin using

0 comments on commit e249b0e

Please sign in to comment.