=====================

The Django admin site

=====================

.. module:: django.contrib.admin

   :synopsis: Django's admin site.

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

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

========

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

       in your :setting:`INSTALLED_APPS` list, add them.

    3. Determine which of your application's models should be editable in the

       admin interface.

    4. For each of those models, optionally create a ``ModelAdmin`` class that

       encapsulates the customized admin functionality and options for that

       particular model.

    5. Instantiate an ``AdminSite`` and tell it about each of your models and

       ``ModelAdmin`` classes.

    6. Hook the ``AdminSite`` instance into your URLconf.

Other topics

------------

.. toctree::

   :maxdepth: 1

   actions

   admindocs

.. seealso::

    For information about serving the media files (images, JavaScript, and CSS)

    associated with the admin in production, see :ref:`serving-media-files`.

``ModelAdmin`` objects

======================

.. class:: ModelAdmin

The ``ModelAdmin`` class is the representation of a model in the admin

interface. These are stored in a file named ``admin.py`` in your application.

Let's take a look at a very simple example of the ``ModelAdmin``::

    from django.contrib import admin

    from myproject.myapp.models import Author

    class AuthorAdmin(admin.ModelAdmin):

        pass

    admin.site.register(Author, AuthorAdmin)

.. admonition:: Do you need a ``ModelAdmin`` object at all?

    In the preceding example, the ``ModelAdmin`` class doesn't define any

    custom values (yet). As a result, the default admin interface will be

    provided. If you are happy with the default admin interface, you don't

    need to define a ``ModelAdmin`` object at all -- you can register the

    model class without providing a ``ModelAdmin`` description. The

    preceding example could be simplified to::

        from django.contrib import admin

        from myproject.myapp.models import Author

        admin.site.register(Author)

``ModelAdmin`` Options

----------------------

The ``ModelAdmin`` is very flexible. It has several options for dealing with

customizing the interface. All options are defined on the ``ModelAdmin``

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

navigation by that field.

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

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.fieldsets

Set ``fieldsets`` to control the layout of admin "add" and "change" pages.

``fieldsets`` is a list of two-tuples, in which each two-tuple represents a

``<fieldset>`` on the admin form page. (A ``<fieldset>`` is a "section" of the

form.)

The two-tuples are in the format ``(name, field_options)``, where ``name`` is a

string representing the title of the fieldset and ``field_options`` is a

dictionary of information about the fieldset, including a list of fields to be

displayed in it.

A full example, taken from the ``django.contrib.flatpages.FlatPage`` model::

    class FlatPageAdmin(admin.ModelAdmin):

        fieldsets = (

            (None, {

                'fields': ('url', 'title', 'content', 'sites')

            }),

            ('Advanced options', {

                'classes': ('collapse',),

                'fields': ('enable_comments', 'registration_required', 'template_name')

            }),

        )

This results in an admin page that looks like:

    .. image:: _images/flatfiles_admin.png

If ``fieldsets`` isn't given, Django will default to displaying each field

that isn't an ``AutoField`` and has ``editable=True``, in a single fieldset,

in the same order as the fields are defined in the model.

The ``field_options`` dictionary can have the following keys:

    * ``fields``

        A tuple of field names to display in this fieldset. This key is

        required.

        Example::

            {

            'fields': ('first_name', 'last_name', 'address', 'city', 'state'),

            }

        To display multiple fields on the same line, wrap those fields in

        their own tuple. In this example, the ``first_name`` and ``last_name``

        fields will display on the same line::

            {

            'fields': (('first_name', 'last_name'), 'address', 'city', 'state'),

            }

        .. versionadded:: 1.2

        ``fields`` can contain values defined in

        :attr:`ModelAdmin.readonly_fields` to be displayed as read-only.

    * ``classes``

        A list containing extra CSS classes to apply to the fieldset.

        Example::

            {

            'classes': ['wide', 'extrapretty'],

            }

        Two useful classes defined by the default admin site stylesheet are

        ``collapse`` and ``wide``. Fieldsets with the ``collapse`` style will

        be initially collapsed in the admin and replaced with a small

        "click to expand" link. Fieldsets with the ``wide`` style will be

        given extra horizontal space.

    * ``description``

        A string of optional extra text to be displayed at the top of each

        fieldset, under the heading of the fieldset.

        Note that this value is *not* HTML-escaped when it's displayed in

        the admin interface. This lets you include HTML if you so desire.

        Alternatively you can use plain text and

        ``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

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

interface.

.. attribute:: ModelAdmin.list_display

Set ``list_display`` to control which fields are displayed on the change list

page of the admin.

Example::

    list_display = ('first_name', 'last_name')

If you don't set ``list_display``, the admin site will display a single column

that displays the ``__unicode__()`` representation of each object.

You have four possible values that can be used in ``list_display``:

    * A field of the model. For example::

          class PersonAdmin(admin.ModelAdmin):

              list_display = ('first_name', 'last_name')

    * A callable that accepts one parameter for the model instance. For

      example::

          def upper_case_name(obj):

              return ("%s %s" % (obj.first_name, obj.last_name)).upper()

          upper_case_name.short_description = 'Name'

          class PersonAdmin(admin.ModelAdmin):

              list_display = (upper_case_name,)

    * A string representing an attribute on the ``ModelAdmin``. This behaves

      same as the callable. For example::

          class PersonAdmin(admin.ModelAdmin):

              list_display = ('upper_case_name',)

              def upper_case_name(self, obj):

                return ("%s %s" % (obj.first_name, obj.last_name)).upper()

              upper_case_name.short_description = 'Name'

    * A string representing an attribute on the model. This behaves almost

      the same as the callable, but ``self`` in this context is the model

      instance. Here's a full model example::

          class Person(models.Model):

              name = models.CharField(max_length=50)

              birthday = models.DateField()

              def decade_born_in(self):

                  return self.birthday.strftime('%Y')[:3] + "0's"

              decade_born_in.short_description = 'Birth decade'

          class PersonAdmin(admin.ModelAdmin):

              list_display = ('name', 'decade_born_in')

A few special cases to note about ``list_display``:

    * If the field is a ``ForeignKey``, Django will display the

      ``__unicode__()`` of the related object.

    * ``ManyToManyField`` fields aren't supported, because that would entail

      executing a separate SQL statement for each row in the table. If you

      want to do this nonetheless, give your model a custom method, and add

      that method's name to ``list_display``. (See below for more on custom

      methods in ``list_display``.)

    * If the field is a ``BooleanField`` or ``NullBooleanField``, Django will

      display a pretty "on" or "off" icon instead of ``True`` or ``False``.

    * If the string given is a method of the model, ``ModelAdmin`` or a

      callable, Django will HTML-escape the output by default. If you'd rather

      not escape the output of the method, give the method an ``allow_tags``

      attribute whose value is ``True``.

      Here's a full example model::

          class Person(models.Model):

              first_name = models.CharField(max_length=50)

              last_name = models.CharField(max_length=50)

              color_code = models.CharField(max_length=6)

              def colored_name(self):

                  return '<span style="color: #%s;">%s %s</span>' % (self.color_code, self.first_name, self.last_name)

              colored_name.allow_tags = True

          class PersonAdmin(admin.ModelAdmin):

              list_display = ('first_name', 'last_name', 'colored_name')

    * If the string given is a method of the model, ``ModelAdmin`` or a

      callable that returns True or False Django will display a pretty "on" or

      "off" icon if you give the method a ``boolean`` attribute whose value is

      ``True``.

      Here's a full example model::

          class Person(models.Model):

              first_name = models.CharField(max_length=50)

              birthday = models.DateField()

              def born_in_fifties(self):

                  return self.birthday.strftime('%Y')[:3] == '195'

              born_in_fifties.boolean = True

          class PersonAdmin(admin.ModelAdmin):

              list_display = ('name', 'born_in_fifties')

    * The ``__str__()`` and ``__unicode__()`` methods are just as valid in

      ``list_display`` as any other model method, so it's perfectly OK to do

      this::

          list_display = ('__unicode__', 'some_other_field')

    * Usually, elements of ``list_display`` that aren't actual database fields

      can't be used in sorting (because Django does all the sorting at the

      database level).

      However, if an element of ``list_display`` represents a certain database

      field, you can indicate this fact by setting the ``admin_order_field``

      attribute of the item.

      For example::

        class Person(models.Model):

            first_name = models.CharField(max_length=50)

            color_code = models.CharField(max_length=6)

            def colored_first_name(self):

                return '<span style="color: #%s;">%s</span>' % (self.color_code, self.first_name)

            colored_first_name.allow_tags = True

            colored_first_name.admin_order_field = 'first_name'

        class PersonAdmin(admin.ModelAdmin):

            list_display = ('first_name', 'colored_first_name')

      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.

By default, the change list page will link the first column -- the first field

specified in ``list_display`` -- to the change page for each item. But

``list_display_links`` lets you change which columns are linked. Set

``list_display_links`` to a list or tuple of field names (in the same format as

``list_display``) to link.

``list_display_links`` can specify one or many field names. As long as the

field names appear in ``list_display``, Django doesn't care how many (or how

few) fields are linked. The only requirement is: If you want to use

``list_display_links``, you must define ``list_display``.

In this example, the ``first_name`` and ``last_name`` fields will be linked on

the change list page::

    class PersonAdmin(admin.ModelAdmin):

        list_display = ('first_name', 'last_name', 'birthday')

        list_display_links = ('first_name', 'last_name')

.. _admin-list-editable:

.. attribute:: ModelAdmin.list_editable

.. versionadded:: 1.1

Set ``list_editable`` to a list of field names on the model which will allow

editing on the change list page. That is, fields listed in ``list_editable``

will be displayed as form widgets on the change list page, allowing users to

edit and save multiple rows at once.

.. note::

    ``list_editable`` interacts with a couple of other options in particular

    ways; you should note the following rules:

        * Any field in ``list_editable`` must also be in ``list_display``. You

          can't edit a field that's not displayed!

        * The same field can't be listed in both ``list_editable`` and

          ``list_display_links`` -- a field can't be both a form and a link.

    You'll get a validation error if either of these rules are broken.

.. 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

field should be either a ``BooleanField``, ``CharField``, ``DateField``,

``DateTimeField``, ``IntegerField`` or ``ForeignKey``.

This example, taken from the ``django.contrib.auth.models.User`` model, shows

how both ``list_display`` and ``list_filter`` work::

    class UserAdmin(admin.ModelAdmin):

        list_display = ('username', 'email', 'first_name', 'last_name', 'is_staff')

        list_filter = ('is_staff', 'is_superuser')

The above code results in an admin change list page that looks like this:

    .. image:: _images/users_changelist.png

(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

:meth:`~django.db.models.QuerySet.select_related` in retrieving the list of

objects on the admin change list page. This can save you a bunch of database

queries.

The value should be either ``True`` or ``False``. Default is ``False``.

Note that Django will use :meth:`~django.db.models.QuerySet.select_related`,

regardless of this setting, if one of the ``list_display`` fields is a

``ForeignKey``.

.. 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

``ordering`` parameter.

If this isn't provided, the Django admin will use the model's default ordering.

.. admonition:: Note

    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::

    class ArticleAdmin(admin.ModelAdmin):

        prepopulated_fields = {"slug": ("title",)}

When set, the given fields will use a bit of JavaScript to populate from the

fields assigned. The main use for this functionality is to automatically

generate the value for ``SlugField`` fields from one or more other fields. The

generated value is produced by concatenating the values of the source fields,

and then by transforming that result into a valid slug (e.g. substituting

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

in ``radio_fields``, Django will use a radio-button interface instead.

Assuming ``group`` is a ``ForeignKey`` on the ``Person`` model::

    class PersonAdmin(admin.ModelAdmin):

        radio_fields = {"group": admin.VERTICAL}