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

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 from your models to provide a quick, model-centric interface

where trusted users can manage content on your site. The admin's recommended

use is limited to an organization's internal management tool. It's not intended

for building your entire front end around.

The admin has many hooks for customization, but beware of trying to use those

hooks exclusively. If you need to provide a more process-centric interface

that abstracts away the implementation details of database tables and fields,

then it's probably time to write your own views.

In this document we discuss how to activate, use, and customize Django's admin

interface.

Overview

========

The admin is enabled in the default project template used by

:djadmin:`startproject`.

If you're not using the default project template, here are the requirements:

#. Add ``'django.contrib.admin'`` and its dependencies -

   :mod:`django.contrib.auth`, :mod:`django.contrib.contenttypes`,

   :mod:`django.contrib.messages`, and :mod:`django.contrib.sessions` - to your

   :setting:`INSTALLED_APPS` setting.

#. Configure a :class:`~django.template.backends.django.DjangoTemplates`

   backend in your :setting:`TEMPLATES` setting with

   ``django.template.context_processors.request``,

   ``django.contrib.auth.context_processors.auth``, and

   ``django.contrib.messages.context_processors.messages`` in

   the ``'context_processors'`` option of :setting:`OPTIONS

   <TEMPLATES-OPTIONS>`.

#. If you've customized the :setting:`MIDDLEWARE` setting,

   :class:`django.contrib.auth.middleware.AuthenticationMiddleware` and

   :class:`django.contrib.messages.middleware.MessageMiddleware` must be

   included.

#. :ref:`Hook the admin's URLs into your URLconf

   <hooking-adminsite-to-urlconf>`.

After you've taken these steps, you'll be able to use the admin site by

visiting the URL you hooked it into (``/admin/``, by default).

If you need to create a user to login with, use the :djadmin:`createsuperuser`

command. By default, logging in to the admin requires that the user has the

:attr:`~.User.is_staff` attribute set to ``True``.

Finally, determine which of your application's models should be editable in the

admin interface. For each of those models, register them with the admin as

described in :class:`ModelAdmin`.

Other topics

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

.. toctree::

   :maxdepth: 1

   actions

   filters

   admindocs

   javascript

.. seealso::

    For information about serving the static files (images, JavaScript, and

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

    Having problems?  Try :doc:`/faq/admin`.

``ModelAdmin`` objects

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

.. class:: ModelAdmin

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

    interface. Usually, these are stored in a file named ``admin.py`` in your

    application. Let's take a look at an example of the ``ModelAdmin``::

        from django.contrib import admin

        from 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 myapp.models import Author

            admin.site.register(Author)

The ``register`` decorator

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

.. function:: register(*models, site=django.contrib.admin.sites.site)

    There is also a decorator for registering your ``ModelAdmin`` classes::

        from django.contrib import admin

        from .models import Author

        @admin.register(Author)

        class AuthorAdmin(admin.ModelAdmin):

            pass

    It's given one or more model classes to register with the ``ModelAdmin``.

    If you're using a custom :class:`AdminSite`, pass it using the ``site`` keyword

    argument::

        from django.contrib import admin

        from .models import Author, Editor, Reader

        from myproject.admin_site import custom_admin_site

        @admin.register(Author, Reader, Editor, site=custom_admin_site)

        class PersonAdmin(admin.ModelAdmin):

            pass

    You can't use this decorator if you have to reference your model admin

    class in its ``__init__()`` method, e.g.

    ``super(PersonAdmin, self).__init__(*args, **kwargs)``. You can use

    ``super().__init__(*args, **kwargs)``.

Discovery of admin files

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

When you put ``'django.contrib.admin'`` in your :setting:`INSTALLED_APPS`

setting, Django automatically looks for an ``admin`` module in each

application and imports it.

.. class:: apps.AdminConfig

    This is the default :class:`~django.apps.AppConfig` class for the admin.

    It calls :func:`~django.contrib.admin.autodiscover()` when Django starts.

.. class:: apps.SimpleAdminConfig

    This class works like :class:`~django.contrib.admin.apps.AdminConfig`,

    except it doesn't call :func:`~django.contrib.admin.autodiscover()`.

    .. attribute:: default_site

        A dotted import path to the default admin site's class or to a callable

        that returns a site instance. Defaults to

        ``'django.contrib.admin.sites.AdminSite'``. See

        :ref:`overriding-default-admin-site` for usage.

.. function:: autodiscover

    This function attempts to import an ``admin`` module in each installed

    application. Such modules are expected to register models with the admin.

    Typically you won't need to call this function directly as

    :class:`~django.contrib.admin.apps.AdminConfig` calls it when Django starts.

If you are using a custom ``AdminSite``, it is common to import all of the

``ModelAdmin`` subclasses into your code and register them to the custom

``AdminSite``. In that case, in order to disable auto-discovery, you should

put ``'django.contrib.admin.apps.SimpleAdminConfig'`` instead of

``'django.contrib.admin'`` in your :setting:`INSTALLED_APPS` setting.

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

    from django.contrib import admin

    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

    Controls whether a selection counter is displayed 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``

    in your model, and the change list page will include a date-based drilldown

    navigation by that field.

    Example::

        date_hierarchy = 'pub_date'

    You can also specify a field on a related model using the ``__`` lookup,

    for example::

        date_hierarchy = 'author__pub_date'

    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.

    .. note::

        ``date_hierarchy`` uses :meth:`QuerySet.datetimes()

        <django.db.models.query.QuerySet.datetimes>` internally. Please refer

        to its documentation for some caveats when time zone support is

        enabled (:setting:`USE_TZ = True <USE_TZ>`).

.. attribute:: ModelAdmin.empty_value_display

    This attribute overrides the default display value for record's fields that

    are empty (``None``, empty string, etc.). The default value is ``-`` (a

    dash). For example::

        from django.contrib import admin

        class AuthorAdmin(admin.ModelAdmin):

            empty_value_display = '-empty-'

    You can also override ``empty_value_display`` for all admin pages with

    :attr:`AdminSite.empty_value_display`, or for specific fields like this::

        from django.contrib import admin

        class AuthorAdmin(admin.ModelAdmin):

            list_display = ('name', 'title', 'view_birth_date')

            @admin.display(empty_value='???')

            def view_birth_date(self, obj):

                return obj.birth_date

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

        from django.db import models

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

        from django.contrib import admin

        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 the ``fields`` option to make simple layout changes in the forms on

    the "add" and "change" pages such as showing only a subset of available

    fields, modifying their order, or grouping them into rows. For example, you

    could define a simpler version of the admin form for the

    :class:`django.contrib.flatpages.models.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. ``fields`` can contain

    values defined in :attr:`ModelAdmin.readonly_fields` to be displayed as

    read-only.

    For more complex layout needs, see the :attr:`~ModelAdmin.fieldsets` option.

    The ``fields`` option accepts the same types of values as

    :attr:`~ModelAdmin.list_display`, except that callables aren't accepted.

    Names of model and model admin methods will only be used if they're listed

    in :attr:`~ModelAdmin.readonly_fields`.

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

    tuple. In this example, the ``url`` and ``title`` fields will display on the

    same line and the ``content`` field will be displayed below them on its

    own line::

        class FlatPageAdmin(admin.ModelAdmin):

            fields = (('url', 'title'), 'content')

    .. admonition:: Note

        This ``fields`` option should not be confused with the ``fields``

        dictionary key that is within the :attr:`~ModelAdmin.fieldsets` option,

        as described in the next section.

    If neither ``fields`` nor :attr:`~ModelAdmin.fieldsets` options are present,

    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.

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

    :class:`django.contrib.flatpages.models.FlatPage` model::

        from django.contrib import admin

        class FlatPageAdmin(admin.ModelAdmin):

            fieldsets = (

                (None, {

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

                }),

                ('Advanced options', {

                    'classes': ('collapse',),

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

                }),

            )

    This results in an admin page that looks like:

    .. image:: _images/fieldsets.png

    If neither ``fieldsets`` nor :attr:`~ModelAdmin.fields` options are present,

    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'),

            }

        As with the :attr:`~ModelAdmin.fields` option, 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'),

            }

        ``fields`` can contain values defined in

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

        If you add the name of a callable to ``fields``, the same rule applies

        as with the :attr:`~ModelAdmin.fields` option: the callable must be

        listed in :attr:`~ModelAdmin.readonly_fields`.

    * ``classes``

        A list or tuple 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. This string is not

        rendered for :class:`~django.contrib.admin.TabularInline` due to its

        layout.

        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

        :func:`django.utils.html.escape` to escape any HTML special

        characters.

.. attribute:: ModelAdmin.filter_horizontal

    By default, a :class:`~django.db.models.ManyToManyField` is displayed in

    the admin site with a ``<select multiple>``. However, multiple-select boxes

    can be difficult to use when selecting many items. Adding a

    :class:`~django.db.models.ManyToManyField` to this list will instead use

    a nifty unobtrusive JavaScript "filter" interface that allows searching

    within the options. The unselected and selected options appear in two boxes

    side by side. See :attr:`~ModelAdmin.filter_vertical` to use a vertical

    interface.

.. attribute:: ModelAdmin.filter_vertical

    Same as :attr:`~ModelAdmin.filter_horizontal`, but uses a vertical display

    of the filter interface with the box of unselected options appearing above

    the box of selected options.

.. 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. Alternatively, you can customize the default

    form rather than specifying an entirely new one by using the

    :meth:`ModelAdmin.get_form` method.

    For an example see the section :ref:`admin-custom-validation`.

    .. admonition:: Note

        If you define the ``Meta.model`` attribute on a

        :class:`~django.forms.ModelForm`, you must also define the

        ``Meta.fields`` attribute (or the ``Meta.exclude`` attribute). However,

        since the admin has its own way of defining fields, the ``Meta.fields``

        attribute will be ignored.

        If the ``ModelForm`` is only going to be used for the admin, the easiest

        solution is to omit the ``Meta.model`` attribute, since ``ModelAdmin``

        will provide the correct model to use. Alternatively, you can set

        ``fields = []`` in the ``Meta`` class to satisfy the validation on the

        ``ModelForm``.

    .. admonition:: Note

        If your ``ModelForm`` and ``ModelAdmin`` both define an ``exclude``

        option then ``ModelAdmin`` takes precedence::

            from django import forms

            from django.contrib import admin

            from myapp.models import Person

            class PersonForm(forms.ModelForm):

                class Meta:

                    model = Person

                    exclude = ['name']

            class PersonAdmin(admin.ModelAdmin):

                exclude = ['age']

                form = PersonForm

        In the above example, the "age" field will be excluded but the "name"

        field will be included in the generated form.

.. 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.contrib import admin

        from django.db import models

        # Import our custom widget and our model from where they're defined

        from myapp.models import MyModel

        from myapp.widgets import RichTextEditorWidget

        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

    the form field's ``__init__()`` method. 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``, ``radio_fields``, or

        ``autocomplete_fields``.

        ``formfield_overrides`` won't let you change the widget on relation

        fields that have ``raw_id_fields``, ``radio_fields``, or

        ``autocomplete_fields`` set. That's because ``raw_id_fields``,

        ``radio_fields``, and ``autocomplete_fields`` imply custom widgets of

        their own.

.. attribute:: ModelAdmin.inlines

    See :class:`InlineModelAdmin` objects below as well as

    :meth:`ModelAdmin.get_formsets_with_inlines`.

.. 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 ``__str__()`` representation of each object.

    There are four types of values that can be used in ``list_display``. All

    but the simplest may use the  :func:`~django.contrib.admin.display`

    decorator, which is used to customize how the field is presented:

    * The name of a model field. For example::

          class PersonAdmin(admin.ModelAdmin):

              list_display = ('first_name', 'last_name')

    * A callable that accepts one argument, the model instance. For example::

          @admin.display(description='Name')

          def upper_case_name(obj):

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

          class PersonAdmin(admin.ModelAdmin):

              list_display = (upper_case_name,)

    * A string representing a ``ModelAdmin`` method that accepts one argument,

      the model instance. For example::

          class PersonAdmin(admin.ModelAdmin):

              list_display = ('upper_case_name',)

              @admin.display(description='Name')

              def upper_case_name(self, obj):

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

    * A string representing a model attribute or method (without any required

      arguments). For example::

          from django.contrib import admin

          from django.db import models

          class Person(models.Model):

              name = models.CharField(max_length=50)

              birthday = models.DateField()

              @admin.display(description='Birth decade')

              def decade_born_in(self):

                  return '%d’s' % (self.birthday.year // 10 * 10)

          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

      ``__str__()`` 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``, Django will display a pretty "yes",

      "no", or "unknown" icon instead of ``True``, ``False``, or ``None``.

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

      callable, Django will HTML-escape the output by default. To escape

      user input and allow your own unescaped tags, use

      :func:`~django.utils.html.format_html`.

      Here's a full example model::

          from django.contrib import admin

          from django.db import models

          from django.utils.html import format_html

          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)

              @admin.display

              def colored_name(self):

                  return format_html(

                      '<span style="color: #{};">{} {}</span>',

                      self.color_code,

                      self.first_name,

                      self.last_name,

                  )

          class PersonAdmin(admin.ModelAdmin):

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

    * As some examples have already demonstrated, when using a callable, a

      model method, or a ``ModelAdmin`` method, you can customize the column's

      title by wrapping the callable with the

      :func:`~django.contrib.admin.display` decorator and passing the

      ``description`` argument.

    * If the value of a field is ``None``, an empty string, or an iterable

      without elements, Django will display ``-`` (a dash). You can override

      this with :attr:`AdminSite.empty_value_display`::

          from django.contrib import admin

          admin.site.empty_value_display = '(None)'

      You can also use :attr:`ModelAdmin.empty_value_display`::

          class PersonAdmin(admin.ModelAdmin):

              empty_value_display = 'unknown'

      Or on a field level::

          class PersonAdmin(admin.ModelAdmin):

              list_display = ('name', 'birth_date_view')

              @admin.display(empty_value='unknown')

              def birth_date_view(self, obj):

                   return obj.birth_date

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

      callable that returns ``True``, ``False``, or ``None``, Django will

      display a pretty "yes", "no", or "unknown" icon if you wrap the method

      with the :func:`~django.contrib.admin.display` decorator passing the

      ``boolean`` argument with the value set to ``True``::

          from django.contrib import admin

          from django.db import models

          class Person(models.Model):

              first_name = models.CharField(max_length=50)

              birthday = models.DateField()

              @admin.display(boolean=True)

              def born_in_fifties(self):

                  return 1950 <= self.birthday.year < 1960

          class PersonAdmin(admin.ModelAdmin):

              list_display = ('name', 'born_in_fifties')

    * The ``__str__()`` method is just as valid in ``list_display`` as any

      other model method, so it's perfectly OK to do this::

          list_display = ('__str__', '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 using the

      :func:`~django.contrib.admin.display` decorator on the method, passing

      the ``ordering`` argument::

          from django.contrib import admin

          from django.db import models

          from django.utils.html import format_html

          class Person(models.Model):

              first_name = models.CharField(max_length=50)

              color_code = models.CharField(max_length=6)

              @admin.display(ordering='first_name')

              def colored_first_name(self):

                  return format_html(

                      '<span style="color: #{};">{}</span>',

                      self.color_code,

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

      To indicate descending order with the ``ordering`` argument you can use a

      hyphen prefix on the field name. Using the above example, this would look

      like::

          @admin.display(ordering='-first_name')

      The ``ordering`` argument supports query lookups to sort by values on

      related models. This example includes an "author first name" column in

      the list display and allows sorting it by first name::

          class Blog(models.Model):

              title = models.CharField(max_length=255)

              author = models.ForeignKey(Person, on_delete=models.CASCADE)

          class BlogAdmin(admin.ModelAdmin):

              list_display = ('title', 'author', 'author_first_name')

              @admin.display(ordering='author__first_name')

              def author_first_name(self, obj):

                  return obj.author.first_name

      :doc:`Query expressions </ref/models/expressions>` may be used with the

      ``ordering`` argument::

          from django.db.models import Value

          from django.db.models.functions import Concat

          class Person(models.Model):

              first_name = models.CharField(max_length=50)

              last_name = models.CharField(max_length=50)

              @admin.display(ordering=Concat('first_name', Value(' '), 'last_name'))

              def full_name(self):

                  return self.first_name + ' ' + self.last_name

    * Elements of ``list_display`` can also be properties::

          class Person(models.Model):

              first_name = models.CharField(max_length=50)

              last_name = models.CharField(max_length=50)

              @property

              @admin.display(

                  ordering='last_name',

                  description='Full name of the person',

              )

              def full_name(self):

                  return self.first_name + ' ' + self.last_name

          class PersonAdmin(admin.ModelAdmin):

              list_display = ('full_name',)

      Note that ``@property`` must be above ``@display``. If you're using the

      old way -- setting the display-related attributes directly rather than

      using the :func:`~django.contrib.admin.display` decorator --  be aware

      that the ``property()`` function and **not** the ``@property`` decorator

      must be used::

          def my_property(self):

              return self.first_name + ' ' + self.last_name

          my_property.short_description = "Full name of the person"

          my_property.admin_order_field = 'last_name'

          full_name = property(my_property)

    * The field names in ``list_display`` will also appear as CSS classes in

      the HTML output, in the form of ``column-<field_name>`` on each ``<th>``

      element. This can be used to set column widths in a CSS file for example.

    * Django will try to interpret every element of ``list_display`` in this

      order:

      * A field of the model.

      * A callable.

      * A string representing a ``ModelAdmin`` attribute.

      * A string representing a model attribute.

      For example if you have ``first_name`` as a model field and

      as a ``ModelAdmin`` attribute, the model field will be used.

.. attribute:: ModelAdmin.list_display_links

    Use ``list_display_links`` to control if and which fields in

    :attr:`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 this:

    * Set it to ``None`` to get no links at all.

    * Set it to a list or tuple of fields (in the same format as

      ``list_display``) whose columns you want converted to links.

      You can specify one or many fields. As long as the fields appear in

      ``list_display``, Django doesn't care how many (or how few) fields are

      linked. The only requirement is that if you want to use

      ``list_display_links`` in this fashion, 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')

    In this example, the change list page grid will have no links::

        class AuditEntryAdmin(admin.ModelAdmin):

            list_display = ('timestamp', 'message')

            list_display_links = None

.. _admin-list-editable:

.. attribute:: ModelAdmin.list_editable

    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.

    At it's simplest ``list_filter`` takes a list or tuple of field names to

    activate filtering upon, but several more advanced options as available.

    See :ref:`modeladmin-list-filters` for the details.

.. attribute:: ModelAdmin.list_max_show_all

    Set ``list_max_show_all`` to control how many items can appear on a "Show

    all" admin change list page. The admin will display a "Show all" link on the

    change list only if the total result count is less than or equal to this

    setting. By default, this is set to ``200``.

.. 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.query.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 a boolean, a list or a tuple. Default is

    ``False``.

    When value is ``True``, ``select_related()`` will always be called. When

    value is set to ``False``, Django will look at ``list_display`` and call

    ``select_related()`` if any ``ForeignKey`` is present.

    If you need more fine-grained control, use a tuple (or list) as value for

    ``list_select_related``. Empty tuple will prevent Django from calling

    ``select_related`` at all. Any other tuple will be passed directly to

    ``select_related`` as parameters. For example::

        class ArticleAdmin(admin.ModelAdmin):

            list_select_related = ('author', 'category')

    will call ``select_related('author', 'category')``.

    If you need to specify a dynamic value based on the request, you can

    implement a :meth:`~ModelAdmin.get_list_select_related` method.

    .. note::

        ``ModelAdmin`` ignores this attribute when

        :meth:`~django.db.models.query.QuerySet.select_related` was already

        called on the changelist's ``QuerySet``.

.. 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 :attr:`~django.db.models.Options.ordering` parameter.

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

    ordering.

    If you need to specify a dynamic order (for example depending on user or

    language) you can implement a :meth:`~ModelAdmin.get_ordering` method.

    .. admonition:: Performance considerations with ordering and sorting

        To ensure a deterministic ordering of results, the changelist adds

        ``pk`` to the ordering if it can't find a single or unique together set

        of fields that provide total ordering.

        For example, if the default ordering is by a non-unique ``name`` field,

        then the changelist is sorted by ``name`` and ``pk``. This could

        perform poorly if you have a lot of rows and don't have an index on

        ``name`` and ``pk``.

.. attribute:: ModelAdmin.paginator

    The paginator class to be used for pagination. By default,

    :class:`django.core.paginator.Paginator` is used. If the custom paginator

    class doesn't have the same constructor interface as

    :class:`django.core.paginator.Paginator`, you will also need to

    provide an implementation for :meth:`ModelAdmin.get_paginator`.

.. 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 and lowercasing ASCII letters).

    Prepopulated fields aren't modified by JavaScript after a value has been

    saved. It's usually undesired that slugs change (which would cause an

    object's URL to change if the slug is used in it).

    ``prepopulated_fields`` doesn't accept ``DateTimeField``, ``ForeignKey``,

    ``OneToOneField``, and ``ManyToManyField`` fields.

.. attribute:: ModelAdmin.preserve_filters

    By default, applied filters are preserved on the list view after creating,

    editing, or deleting an object. You can have filters cleared by setting

    this attribute to ``False``.

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

    You have the choice of using ``HORIZONTAL`` or ``VERTICAL`` from the

    ``django.contrib.admin`` module.

    Don't include a field in ``radio_fields`` unless it's a ``ForeignKey`` or has

    ``choices`` set.

.. attribute:: ModelAdmin.autocomplete_fields

    ``autocomplete_fields`` is a list of ``ForeignKey`` and/or

    ``ManyToManyField`` fields you would like to change to `Select2

    <https://select2.org/>`_ autocomplete inputs.

    By default, the admin uses a select-box interface (``<select>``) for

    those fields. Sometimes you don't want to incur the overhead of selecting

    all the related instances to display in the dropdown.

    The Select2 input looks similar to the default input but comes with a

    search feature that loads the options asynchronously. This is faster and

    more user-friendly if the related model has many instances.

    You must define :attr:`~ModelAdmin.search_fields` on the related object's

    ``ModelAdmin`` because the autocomplete search uses it.

    To avoid unauthorized data disclosure, users must have the ``view`` or

    ``change`` permission to the related object in order to use autocomplete.

    Ordering and pagination of the results are controlled by the related

    ``ModelAdmin``'s :meth:`~ModelAdmin.get_ordering` and

    :meth:`~ModelAdmin.get_paginator` methods.

    In the following example, ``ChoiceAdmin`` has an autocomplete field for the

    ``ForeignKey`` to the ``Question``. The results are filtered by the

    ``question_text`` field and ordered by the ``date_created`` field::

        class QuestionAdmin(admin.ModelAdmin):

            ordering = ['date_created']

            search_fields = ['question_text']

        class ChoiceAdmin(admin.ModelAdmin):

            autocomplete_fields = ['question']

    .. admonition:: Performance considerations for large datasets

        Ordering using :attr:`ModelAdmin.ordering` may cause performance

        problems as sorting on a large queryset will be slow.

        Also, if your search fields include fields that aren't indexed by the

        database, you might encounter poor performance on extremely large

        tables.

        For those cases, it's a good idea to write your own

        :func:`ModelAdmin.get_search_results` implementation using a

        full-text indexed search.

        You may also want to change the ``Paginator`` on very large tables

        as the default paginator always performs a ``count()`` query.

        For example, you could override the default implementation of the

        ``Paginator.count`` property.

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

    overhead of having to select all the related instances to display in the

    drop-down.

    ``raw_id_fields`` is a list of fields you would like to change

    into an ``Input`` widget for either a ``ForeignKey`` or

    ``ManyToManyField``::

        class ArticleAdmin(admin.ModelAdmin):

            raw_id_fields = ("newspaper",)

    The ``raw_id_fields`` ``Input`` widget should contain a primary key if the

    field is a ``ForeignKey`` or a comma separated list of values if the field

    is a ``ManyToManyField``.  The ``raw_id_fields`` widget shows a magnifying

    glass button next to the field which allows users to search for and select

    a value:

    .. image:: _images/raw_id_fields.png

.. attribute:: ModelAdmin.readonly_fields

    By default the admin shows all fields as editable. Any fields in this

    option (which should be a ``list`` or ``tuple``) will display its data

    as-is and non-editable; they are also excluded from the

    :class:`~django.forms.ModelForm` used for creating and editing. Note that

    when specifying :attr:`ModelAdmin.fields` or :attr:`ModelAdmin.fieldsets`

    the read-only fields must be present to be shown (they are ignored

    otherwise).

    If ``readonly_fields`` is used without defining explicit ordering through

    :attr:`ModelAdmin.fields` or :attr:`ModelAdmin.fieldsets` they will be

    added last after all editable fields.

    A read-only field can not only display data from a model's field, it can

    also display the output of a model's method or a method of the

    ``ModelAdmin`` class itself. This is very similar to the way

    :attr:`ModelAdmin.list_display` behaves. This provides a way to use the

    admin interface to provide feedback on the status of the objects being

    edited, for example::

        from django.contrib import admin

        from django.utils.html import format_html_join

        from django.utils.safestring import mark_safe

        class PersonAdmin(admin.ModelAdmin):

            readonly_fields = ('address_report',)

            # description functions like a model field's verbose_name

            @admin.display(description='Address')

            def address_report(self, instance):

                # assuming get_full_address() returns a list of strings

                # for each line of the address and you want to separate each

                # line by a linebreak

                return format_html_join(

                    mark_safe('<br>'),

                    '{}',

                    ((line,) for line in instance.get_full_address()),

                ) or mark_safe("<span class='errors'>I can't determine this address.</span>")

.. attribute:: ModelAdmin.save_as

    Set ``save_as`` to enable a "save as new" feature on admin change forms.

    Normally, objects have three save options: "Save", "Save and continue

    editing", and "Save and add another". If ``save_as`` is ``True``, "Save

    and add another" will be replaced by a "Save as new" button that creates a

    new object (with a new ID) rather than updating the existing object.

    By default, ``save_as`` is set to ``False``.

.. attribute:: ModelAdmin.save_as_continue

    When :attr:`save_as=True <save_as>`, the default redirect after saving the

    new object is to the change view for that object. If you set

    ``save_as_continue=False``, the redirect will be to the changelist view.

    By default, ``save_as_continue`` is set to ``True``.

.. attribute:: ModelAdmin.save_on_top

    Set ``save_on_top`` to add save buttons across the top of your admin change

    forms.

    Normally, the save buttons appear only at the bottom of the forms. If you

    set ``save_on_top``, the buttons will appear both on the top and the

    bottom.

    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

    somebody submits a search query in that text box.

    These fields should be some kind of text field, such as ``CharField`` or

    ``TextField``. You can also perform a related lookup on a ``ForeignKey`` or

    ``ManyToManyField`` with the lookup API "follow" notation::

        search_fields = ['foreign_key__related_fieldname']

    For example, if you have a blog entry with an author, the following

    definition would enable searching blog entries by the email address of the

    author::

        search_fields = ['user__email']

    When somebody does a search in the admin search box, Django splits the

    search query into words and returns all objects that contain each of the

    words, case-insensitive (using the :lookup:`icontains` lookup), where each

    word must be in at least one of ``search_fields``. For example, if

    ``search_fields`` is set to ``['first_name', 'last_name']`` and a user

    searches for ``john lennon``, Django will do the equivalent of this SQL

    ``WHERE`` clause:

    .. code-block:: sql

        WHERE (first_name ILIKE '%john%' OR last_name ILIKE '%john%')

        AND (first_name ILIKE '%lennon%' OR last_name ILIKE '%lennon%')

    The search query can contain quoted phrases with spaces. For example, if a

    user searches for ``"john winston"`` or ``'john winston'``, Django will do

    the equivalent of this SQL ``WHERE`` clause:

    .. code-block:: sql

        WHERE (first_name ILIKE '%john winston%' OR last_name ILIKE '%john winston%')

    If you don't want to use ``icontains`` as the lookup, you can use any

    lookup by appending it the field. For example, you could use :lookup:`exact`

    by setting ``search_fields`` to ``['first_name__exact']``.

    Some (older) shortcuts for specifying a field lookup are also available.

    You can prefix a field in ``search_fields`` with the following characters

    and it's equivalent to adding ``__<lookup>`` to the field:

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

    Prefix  Lookup

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

    ^       :lookup:`startswith`

    =       :lookup:`iexact`

    @       :lookup:`search`

    None    :lookup:`icontains`

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

    If you need to customize search you can use

    :meth:`ModelAdmin.get_search_results` to provide additional or alternate

    search behavior.

    .. versionchanged:: 4.1

        Searches using multiple search terms are now applied in a single call

        to ``filter()``, rather than in sequential ``filter()`` calls.

        For multi-valued relationships, this means that rows from the related

        model must match all terms rather than any term. For example, if

        ``search_fields`` is set to ``['child__name', 'child__age']``, and a

        user searches for ``'Jamal 17'``, parent rows will be returned only if

        there is a relationship to some 17-year-old child named Jamal, rather

        than also returning parents who merely have a younger or older child

        named Jamal in addition to some other 17-year-old.

        See the :ref:`spanning-multi-valued-relationships` topic for more

        discussion of this difference.

.. attribute:: ModelAdmin.search_help_text

    .. versionadded:: 4.0

    Set ``search_help_text`` to specify a descriptive text for the search box

    which will be displayed below it.

.. attribute:: ModelAdmin.show_full_result_count

    Set ``show_full_result_count`` to control whether the full count of objects

    should be displayed on a filtered admin page (e.g. ``99 results (103 total)``).

    If this option is set to ``False``, a text like ``99 results (Show all)``

    is displayed instead.

    The default of ``show_full_result_count=True`` generates a query to perform

    a full count on the table which can be expensive if the table contains a

    large number of rows.

.. attribute:: ModelAdmin.sortable_by

    By default, the change list page allows sorting by all model fields (and

    callables that use the ``ordering`` argument to the

    :func:`~django.contrib.admin.display` decorator or have the

    ``admin_order_field`` attribute) specified in :attr:`list_display`.

    If you want to disable sorting for some columns, set ``sortable_by`` to

    a collection (e.g. ``list``, ``tuple``, or ``set``) of the subset of

    :attr:`list_display` that you want to be sortable. An empty collection

    disables sorting for all columns.

    If you need to specify this list dynamically, implement a

    :meth:`~ModelAdmin.get_sortable_by` method instead.

.. attribute:: ModelAdmin.view_on_site

    Set ``view_on_site`` to control whether or not to display the "View on site" link.

    This link should bring you to a URL where you can display the saved object.

    This value can be either a boolean flag or a callable. If ``True`` (the

    default), the object's :meth:`~django.db.models.Model.get_absolute_url`

    method will be used to generate the url.

    If your model has a :meth:`~django.db.models.Model.get_absolute_url` method

    but you don't want the "View on site" button to appear, you only need to set

    ``view_on_site`` to ``False``::

        from django.contrib import admin

        class PersonAdmin(admin.ModelAdmin):

            view_on_site = False

    In case it is a callable, it accepts the model instance as a parameter.

    For example::

        from django.contrib import admin

        from django.urls import reverse

        class PersonAdmin(admin.ModelAdmin):

            def view_on_site(self, obj):

                url = reverse('person-detail', kwargs={'slug': obj.slug})

                return 'https://example.com' + url

Custom template options

~~~~~~~~~~~~~~~~~~~~~~~

The :ref:`admin-overriding-templates` section describes how to override or extend

the default admin templates.  Use the following options to override the default

templates used by the :class:`ModelAdmin` views:

.. attribute:: ModelAdmin.add_form_template

    Path to a custom template, used by :meth:`add_view`.

.. attribute:: ModelAdmin.change_form_template

    Path to a custom template, used by :meth:`change_view`.

.. attribute:: ModelAdmin.change_list_template

    Path to a custom template, used by :meth:`changelist_view`.

.. attribute:: ModelAdmin.delete_confirmation_template

    Path to a custom template, used by :meth:`delete_view` for displaying a

    confirmation page when deleting one or more objects.

.. attribute:: ModelAdmin.delete_selected_confirmation_template

    Path to a custom template, used by the ``delete_selected`` action method

    for displaying a confirmation page when deleting one or more objects. See

    the :doc:`actions documentation</ref/contrib/admin/actions>`.

.. attribute:: ModelAdmin.object_history_template

    Path to a custom template, used by :meth:`history_view`.

.. attribute:: ModelAdmin.popup_response_template

    Path to a custom template, used by :meth:`response_add`,

    :meth:`response_change`, and :meth:`response_delete`.

.. _model-admin-methods:

``ModelAdmin`` methods

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

.. warning::

    When overriding :meth:`ModelAdmin.save_model` and

    :meth:`ModelAdmin.delete_model`, your code must save/delete the

    object. They aren't meant for veto purposes, rather they allow you to

    perform extra operations.

.. method:: ModelAdmin.save_model(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 changing the object. Overriding this method allows doing pre- or

    post-save operations. Call ``super().save_model()`` to save the object

    using :meth:`.Model.save`.

    For example to attach ``request.user`` to the object prior to saving::

        from django.contrib import admin

        class ArticleAdmin(admin.ModelAdmin):

            def save_model(self, request, obj, form, change):

                obj.user = request.user

                super().save_model(request, obj, form, change)

.. method:: ModelAdmin.delete_model(request, obj)

    The ``delete_model`` method is given the ``HttpRequest`` and a model

    instance. Overriding this method allows doing pre- or post-delete

    operations. Call ``super().delete_model()`` to delete the object using

    :meth:`.Model.delete`.

.. method:: ModelAdmin.delete_queryset(request, queryset)

    The ``delete_queryset()`` method is given the ``HttpRequest`` and a

    ``QuerySet`` of objects to be deleted. Override this method to customize

    the deletion process for the "delete selected objects" :doc:`action

    <actions>`.

.. method:: ModelAdmin.save_formset(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

    changing the parent object.

    For example, to attach ``request.user`` to each changed formset

    model instance::

        class ArticleAdmin(admin.ModelAdmin):

            def save_formset(self, request, form, formset, change):

                instances = formset.save(commit=False)

                for obj in formset.deleted_objects:

                    obj.delete()

                for instance in instances:

                    instance.user = request.user

                    instance.save()

                formset.save_m2m()

    See also :ref:`saving-objects-in-the-formset`.

.. method:: ModelAdmin.get_ordering(request)

    The ``get_ordering`` method takes a ``request`` as parameter and

    is expected to return a ``list`` or ``tuple`` for ordering similar

    to the :attr:`ordering` attribute. For example::

        class PersonAdmin(admin.ModelAdmin):

            def get_ordering(self, request):

                if request.user.is_superuser:

                    return ['name', 'rank']

                else:

                    return ['name']

.. method:: ModelAdmin.get_search_results(request, queryset, search_term)

    The ``get_search_results`` method modifies the list of objects displayed

    into those that match the provided search term. It accepts the request, a

    queryset that applies the current filters, and the user-provided search term.

    It returns a tuple containing a queryset modified to implement the search, and

    a boolean indicating if the results may contain duplicates.

    The default implementation searches the fields named in :attr:`ModelAdmin.search_fields`.

    This method may be overridden with your own custom search method. For

    example, you might wish to search by an integer field, or use an external

    tool such as `Solr`_ or `Haystack`_. You must establish if the queryset

    changes implemented by your search method may introduce duplicates into the

    results, and return ``True`` in the second element of the return value.

    For example, to search by ``name`` and ``age``, you could use::

        class PersonAdmin(admin.ModelAdmin):

            list_display = ('name', 'age')

            search_fields = ('name',)

            def get_search_results(self, request, queryset, search_term):

                queryset, may_have_duplicates = super().get_search_results(

                    request, queryset, search_term,

                )

                try:

                    search_term_as_int = int(search_term)

                except ValueError:

                    pass

                else:

                    queryset |= self.model.objects.filter(age=search_term_as_int)

                return queryset, may_have_duplicates

    This implementation is more efficient than ``search_fields =

    ('name', '=age')`` which results in a string comparison for the numeric

    field, for example ``... OR UPPER("polls_choice"."votes"::text) = UPPER('4')``

    on PostgreSQL.

    .. versionchanged:: 4.1

        Searches using multiple search terms are now applied in a single call

        to ``filter()``, rather than in sequential ``filter()`` calls.

        For multi-valued relationships, this means that rows from the related

        model must match all terms rather than any term. For example, if

        ``search_fields`` is set to ``['child__name', 'child__age']``, and a

        user searches for ``'Jamal 17'``, parent rows will be returned only if

        there is a relationship to some 17-year-old child named Jamal, rather

        than also returning parents who merely have a younger or older child

        named Jamal in addition to some other 17-year-old.

        See the :ref:`spanning-multi-valued-relationships` topic for more

        discussion of this difference.

.. _Solr: https://solr.apache.org

.. _Haystack: https://haystacksearch.org

.. method:: ModelAdmin.save_related(request, form, formsets, change)

    The ``save_related`` method is given the ``HttpRequest``, the parent

    ``ModelForm`` instance, the list of inline formsets and a boolean value

    based on whether the parent is being added or changed. Here you can do any

    pre- or post-save operations for objects related to the parent. Note

    that at this point the parent object and its form have already been saved.

.. method:: ModelAdmin.get_autocomplete_fields(request)

    The ``get_autocomplete_fields()`` method is given the ``HttpRequest`` and is

    expected to return a ``list`` or ``tuple`` of field names that will be

    displayed with an autocomplete widget as described above in the

    :attr:`ModelAdmin.autocomplete_fields` section.

.. method:: ModelAdmin.get_readonly_fields(request, obj=None)

    The ``get_readonly_fields`` method is given the ``HttpRequest`` and the

    ``obj`` being edited (or ``None`` on an add form) and is expected to return

    a ``list`` or ``tuple`` of field names that will be displayed as read-only,

    as described above in the :attr:`ModelAdmin.readonly_fields` section.

.. method:: ModelAdmin.get_prepopulated_fields(request, obj=None)

    The ``get_prepopulated_fields`` method is given the ``HttpRequest`` and the

    ``obj`` being edited (or ``None`` on an add form) and is expected to return

    a ``dictionary``, as described above in the :attr:`ModelAdmin.prepopulated_fields`

    section.

.. method:: ModelAdmin.get_list_display(request)

    The ``get_list_display`` method is given the ``HttpRequest`` and is

    expected to return a ``list`` or ``tuple`` of field names that will be

    displayed on the changelist view as described above in the

    :attr:`ModelAdmin.list_display` section.

.. method:: ModelAdmin.get_list_display_links(request, list_display)

    The ``get_list_display_links`` method is given the ``HttpRequest`` and

    the ``list`` or ``tuple`` returned by :meth:`ModelAdmin.get_list_display`.

    It is expected to return either ``None`` or a ``list`` or ``tuple`` of field

    names on the changelist that will be linked to the change view, as described

    in the :attr:`ModelAdmin.list_display_links` section.

.. method:: ModelAdmin.get_exclude(request, obj=None)

    The ``get_exclude`` method is given the ``HttpRequest`` and the ``obj``

    being edited (or ``None`` on an add form) and is expected to return a list

    of fields, as described in :attr:`ModelAdmin.exclude`.

.. method:: ModelAdmin.get_fields(request, obj=None)

    The ``get_fields`` method is given the ``HttpRequest`` and the ``obj``

    being edited (or ``None`` on an add form) and is expected to return a list

    of fields, as described above in the :attr:`ModelAdmin.fields` section.

.. method:: ModelAdmin.get_fieldsets(request, obj=None)

    The ``get_fieldsets`` method is given the ``HttpRequest`` and the ``obj``

    being edited (or ``None`` on an add form) and is expected to return a list

    of two-tuples, in which each two-tuple represents a ``<fieldset>`` on the

    admin form page, as described above in the :attr:`ModelAdmin.fieldsets` section.

.. method:: ModelAdmin.get_list_filter(request)

    The ``get_list_filter`` method is given the ``HttpRequest`` and is expected

    to return the same kind of sequence type as for the

    :attr:`~ModelAdmin.list_filter` attribute.

.. method:: ModelAdmin.get_list_select_related(request)

    The ``get_list_select_related`` method is given the ``HttpRequest`` and

    should return a boolean or list as :attr:`ModelAdmin.list_select_related`

    does.

.. method:: ModelAdmin.get_search_fields(request)

    The ``get_search_fields`` method is given the ``HttpRequest`` and is expected

    to return the same kind of sequence type as for the

    :attr:`~ModelAdmin.search_fields` attribute.

.. method:: ModelAdmin.get_sortable_by(request)

    The ``get_sortable_by()`` method is passed the ``HttpRequest`` and is

    expected to return a collection (e.g. ``list``, ``tuple``, or ``set``) of

    field names that will be sortable in the change list page.

    Its default implementation returns :attr:`sortable_by` if it's set,

    otherwise it defers to :meth:`get_list_display`.

    For example, to prevent one or more columns from being sortable::

        class PersonAdmin(admin.ModelAdmin):

            def get_sortable_by(self, request):

                return {*self.get_list_display(request)} - {'rank'}

.. method:: ModelAdmin.get_inline_instances(request, obj=None)

    The ``get_inline_instances`` method is given the ``HttpRequest`` and the

    ``obj`` being edited (or ``None`` on an add form) and is expected to return

    a ``list`` or ``tuple`` of :class:`~django.contrib.admin.InlineModelAdmin`

    objects, as described below in the :class:`~django.contrib.admin.InlineModelAdmin`

    section. For example, the following would return inlines without the default

    filtering based on add, change, delete, and view permissions::

        class MyModelAdmin(admin.ModelAdmin):

            inlines = (MyInline,)

            def get_inline_instances(self, request, obj=None):

                return [inline(self.model, self.admin_site) for inline in self.inlines]

    If you override this method, make sure that the returned inlines are

    instances of the classes defined in :attr:`inlines` or you might encounter

    a "Bad Request" error when adding related objects.

.. method:: ModelAdmin.get_inlines(request, obj)

    The ``get_inlines`` method is given the ``HttpRequest`` and the

    ``obj`` being edited (or ``None`` on an add form) and is expected to return

    an iterable of inlines. You can override this method to dynamically add

    inlines based on the request or model instance instead of specifying them

    in :attr:`ModelAdmin.inlines`.

.. method:: ModelAdmin.get_urls()

    The ``get_urls`` method on a ``ModelAdmin`` returns the URLs to be used for

    that ModelAdmin in the same way as a URLconf.  Therefore you can extend

    them as documented in :doc:`/topics/http/urls`, using the

    ``AdminSite.admin_view()`` wrapper on your views::

        from django.contrib import admin

        from django.template.response import TemplateResponse

        from django.urls import path

        class MyModelAdmin(admin.ModelAdmin):

            def get_urls(self):

                urls = super().get_urls()

                my_urls = [

                    path('my_view/', self.admin_site.admin_view(self.my_view))

                ]

                return my_urls + urls

            def my_view(self, request):

                # ...

                context = dict(

                   # Include common variables for rendering the admin template.

                   self.admin_site.each_context(request),

                   # Anything else you want in the context...

                   key=value,

                )

                return TemplateResponse(request, "sometemplate.html", context)

    If you want to use the admin layout, extend from ``admin/base_site.html``:

    .. code-block:: html+django

       {% extends "admin/base_site.html" %}

       {% block content %}

       ...

       {% endblock %}

    .. note::

        Notice how the ``self.my_view`` function is wrapped in

        ``self.admin_site.admin_view``. This is important, since it ensures two

        things:

        #. Permission checks are run, ensuring only active staff users can

           access the view.

        #. The :func:`django.views.decorators.cache.never_cache` decorator is

           applied to prevent caching, ensuring the returned information is

           up-to-date.

    .. note::

        Notice that the custom patterns are included *before* the regular admin

        URLs: the admin URL patterns are very permissive and will match nearly

        anything, so you'll usually want to prepend your custom URLs to the

        built-in ones.

        In this example, ``my_view`` will be accessed at

        ``/admin/myapp/mymodel/my_view/`` (assuming the admin URLs are included

        at ``/admin/``.)

    If the page is cacheable, but you still want the permission check to be

    performed, you can pass a ``cacheable=True`` argument to

    ``AdminSite.admin_view()``::

        path('my_view/', self.admin_site.admin_view(self.my_view, cacheable=True))

    ``ModelAdmin`` views have ``model_admin`` attributes. Other

    ``AdminSite`` views have ``admin_site`` attributes.

.. method:: ModelAdmin.get_form(request, obj=None, **kwargs)

    Returns a :class:`~django.forms.ModelForm` class for use in the admin add

    and change views, see :meth:`add_view` and :meth:`change_view`.

    The base implementation uses :func:`~django.forms.models.modelform_factory`

    to subclass :attr:`~form`, modified by attributes such as :attr:`~fields`

    and :attr:`~exclude`. So, for example, if you wanted to offer additional

    fields to superusers, you could swap in a different base form like so::

        class MyModelAdmin(admin.ModelAdmin):

            def get_form(self, request, obj=None, **kwargs):

                if request.user.is_superuser:

                    kwargs['form'] = MySuperuserForm

                return super().get_form(request, obj, **kwargs)

    You may also return a custom :class:`~django.forms.ModelForm` class

    directly.

.. method:: ModelAdmin.get_formsets_with_inlines(request, obj=None)

    Yields (``FormSet``, :class:`InlineModelAdmin`) pairs for use in admin add

    and change views.

    For example if you wanted to display a particular inline only in the change

    view, you could override ``get_formsets_with_inlines`` as follows::

        class MyModelAdmin(admin.ModelAdmin):

            inlines = [MyInline, SomeOtherInline]

            def get_formsets_with_inlines(self, request, obj=None):

                for inline in self.get_inline_instances(request, obj):

                    # hide MyInline in the add view

                    if not isinstance(inline, MyInline) or obj is not None:

                        yield inline.get_formset(request, obj), inline

.. method:: ModelAdmin.formfield_for_foreignkey(db_field, request, **kwargs)

    The ``formfield_for_foreignkey`` method on a ``ModelAdmin`` allows you to

    override the default formfield for a foreign keys field. For example, to

    return a subset of objects for this foreign key field based on the user::

        class MyModelAdmin(admin.ModelAdmin):

            def formfield_for_foreignkey(self, db_field, request, **kwargs):

                if db_field.name == "car":

                    kwargs["queryset"] = Car.objects.filter(owner=request.user)

                return super().formfield_for_foreignkey(db_field, request, **kwargs)

    This uses the ``HttpRequest`` instance to filter the ``Car`` foreign key

    field to only display the cars owned by the ``User`` instance.

    For more complex filters, you can use ``ModelForm.__init__()`` method to

    filter based on an ``instance`` of your model (see

    :ref:`fields-which-handle-relationships`). For example::

        class CountryAdminForm(forms.ModelForm):

            def __init__(self, *args, **kwargs):

                super().__init__(*args, **kwargs)

                self.fields['capital'].queryset = self.instance.cities.all()

        class CountryAdmin(admin.ModelAdmin):

            form = CountryAdminForm

.. method:: ModelAdmin.formfield_for_manytomany(db_field, request, **kwargs)

    Like the ``formfield_for_foreignkey`` method, the

    ``formfield_for_manytomany`` method can be overridden to change the

    default formfield for a many to many field. For example, if an owner can

    own multiple cars and cars can belong to multiple owners -- a many to

    many relationship -- you could filter the ``Car`` foreign key field to

    only display the cars owned by the ``User``::

        class MyModelAdmin(admin.ModelAdmin):

            def formfield_for_manytomany(self, db_field, request, **kwargs):

                if db_field.name == "cars":

                    kwargs["queryset"] = Car.objects.filter(owner=request.user)

                return super().formfield_for_manytomany(db_field, request, **kwargs)

.. method:: ModelAdmin.formfield_for_choice_field(db_field, request, **kwargs)

    Like the ``formfield_for_foreignkey`` and ``formfield_for_manytomany``

    methods, the ``formfield_for_choice_field`` method can be overridden to

    change the default formfield for a field that has declared choices. For

    example, if the choices available to a superuser should be different than

    those available to regular staff, you could proceed as follows::

        class MyModelAdmin(admin.ModelAdmin):

            def formfield_for_choice_field(self, db_field, request, **kwargs):

                if db_field.name == "status":

                    kwargs['choices'] = (

                        ('accepted', 'Accepted'),

                        ('denied', 'Denied'),

                    )

                    if request.user.is_superuser:

                        kwargs['choices'] += (('ready', 'Ready for deployment'),)

                return super().formfield_for_choice_field(db_field, request, **kwargs)

    .. admonition:: Note

        Any ``choices`` attribute set on the formfield will be limited to the

        form field only. If the corresponding field on the model has choices

        set, the choices provided to the form must be a valid subset of those

        choices, otherwise the form submission will fail with

        a :exc:`~django.core.exceptions.ValidationError` when the model itself

        is validated before saving.

.. method:: ModelAdmin.get_changelist(request, **kwargs)

    Returns the ``Changelist`` class to be used for listing. By default,

    ``django.contrib.admin.views.main.ChangeList`` is used. By inheriting this

    class you can change the behavior of the listing.

.. method:: ModelAdmin.get_changelist_form(request, **kwargs)

    Returns a :class:`~django.forms.ModelForm` class for use in the ``Formset``

    on the changelist page. To use a custom form, for example::

        from django import forms

        class MyForm(forms.ModelForm):

            pass

        class MyModelAdmin(admin.ModelAdmin):

            def get_changelist_form(self, request, **kwargs):

                return MyForm

    .. admonition:: Note

        If you define the ``Meta.model`` attribute on a

        :class:`~django.forms.ModelForm`, you must also define the

        ``Meta.fields`` attribute (or the ``Meta.exclude`` attribute). However,

        ``ModelAdmin`` ignores this value, overriding it with the

        :attr:`ModelAdmin.list_editable` attribute. The easiest solution is to

        omit the ``Meta.model`` attribute, since ``ModelAdmin`` will provide the

        correct model to use.

.. method::  ModelAdmin.get_changelist_formset(request, **kwargs)

    Returns a :ref:`ModelFormSet <model-formsets>` class for use on the

    changelist page if :attr:`~ModelAdmin.list_editable` is used. To use a

    custom formset, for example::

        from django.forms import BaseModelFormSet

        class MyAdminFormSet(BaseModelFormSet):

            pass

        class MyModelAdmin(admin.ModelAdmin):

            def get_changelist_formset(self, request, **kwargs):

                kwargs['formset'] = MyAdminFormSet

                return super().get_changelist_formset(request, **kwargs)

.. method:: ModelAdmin.lookup_allowed(lookup, value)

    The objects in the changelist page can be filtered with lookups from the

    URL's query string. This is how :attr:`list_filter` works, for example. The

    lookups are similar to what's used in :meth:`.QuerySet.filter` (e.g.

    ``[email protected]``). Since the lookups in the query string

    can be manipulated by the user, they must be sanitized to prevent

    unauthorized data exposure.

    The ``lookup_allowed()`` method is given a lookup path from the query string

    (e.g. ``'user__email'``) and the corresponding value

    (e.g. ``'[email protected]'``), and returns a boolean indicating whether

    filtering the changelist's ``QuerySet`` using the parameters is permitted.

    If ``lookup_allowed()`` returns ``False``, ``DisallowedModelAdminLookup``

    (subclass of :exc:`~django.core.exceptions.SuspiciousOperation`) is raised.

    By default, ``lookup_allowed()`` allows access to a model's local fields,

    field paths used in :attr:`~ModelAdmin.list_filter` (but not paths from

    :meth:`~ModelAdmin.get_list_filter`), and lookups required for

    :attr:`~django.db.models.ForeignKey.limit_choices_to` to function

    correctly in :attr:`~django.contrib.admin.ModelAdmin.raw_id_fields`.

    Override this method to customize the lookups permitted for your

    :class:`~django.contrib.admin.ModelAdmin` subclass.

.. method:: ModelAdmin.has_view_permission(request, obj=None)

    Should return ``True`` if viewing ``obj`` is permitted, ``False`` otherwise.

    If obj is ``None``, should return ``True`` or ``False`` to indicate whether

    viewing of objects of this type is permitted in general (e.g., ``False``

    will be interpreted as meaning that the current user is not permitted to

    view any object of this type).

    The default implementation returns ``True`` if the user has either the

    "change" or "view" permission.

.. method:: ModelAdmin.has_add_permission(request)

    Should return ``True`` if adding an object is permitted, ``False``

    otherwise.

.. method:: ModelAdmin.has_change_permission(request, obj=None)

    Should return ``True`` if editing ``obj`` is permitted, ``False``

    otherwise. If ``obj`` is ``None``, should return ``True`` or ``False`` to

    indicate whether editing of objects of this type is permitted in general

    (e.g., ``False`` will be interpreted as meaning that the current user is

    not permitted to edit any object of this type).

.. method:: ModelAdmin.has_delete_permission(request, obj=None)

    Should return ``True`` if deleting ``obj`` is permitted, ``False``

    otherwise. If ``obj`` is ``None``, should return ``True`` or ``False`` to

    indicate whether deleting objects of this type is permitted in general

    (e.g., ``False`` will be interpreted as meaning that the current user is

    not permitted to delete any object of this type).

.. method:: ModelAdmin.has_module_permission(request)

    Should return ``True`` if displaying the module on the admin index page and

    accessing the module's index page is permitted, ``False`` otherwise.

    Uses :meth:`User.has_module_perms()

    <django.contrib.auth.models.User.has_module_perms>` by default. Overriding

    it does not restrict access to the view, add, change, or delete views,

    :meth:`~ModelAdmin.has_view_permission`,

    :meth:`~ModelAdmin.has_add_permission`,

    :meth:`~ModelAdmin.has_change_permission`, and

    :meth:`~ModelAdmin.has_delete_permission` should be used for that.

.. method:: ModelAdmin.get_queryset(request)

    The ``get_queryset`` method on a ``ModelAdmin`` returns a

    :class:`~django.db.models.query.QuerySet` of all model instances that

    can be edited by the admin site. One use case for overriding this method

    is to show objects owned by the logged-in user::

        class MyModelAdmin(admin.ModelAdmin):

            def get_queryset(self, request):

                qs = super().get_queryset(request)

                if request.user.is_superuser:

                    return qs

                return qs.filter(author=request.user)

.. method:: ModelAdmin.message_user(request, message, level=messages.INFO, extra_tags='', fail_silently=False)

    Sends a message to the user using the :mod:`django.contrib.messages`

    backend.  See the :ref:`custom ModelAdmin example <custom-admin-action>`.

    Keyword arguments allow you to change the message level, add extra CSS

    tags, or fail silently if the ``contrib.messages`` framework is not

    installed. These keyword arguments match those for

    :func:`django.contrib.messages.add_message`, see that function's

    documentation for more details. One difference is that the level may be

    passed as a string label in addition to integer/constant.

.. method:: ModelAdmin.get_paginator(request, queryset, per_page, orphans=0, allow_empty_first_page=True)

    Returns an instance of the paginator to use for this view. By default,

    instantiates an instance of :attr:`paginator`.

.. method:: ModelAdmin.response_add(request, obj, post_url_continue=None)

    Determines the :class:`~django.http.HttpResponse` for the

    :meth:`add_view` stage.

    ``response_add`` is called after the admin form is submitted and

    just after the object and all the related instances have

    been created and saved. You can override it to change the default behavior

    after the object has been created.

.. method:: ModelAdmin.response_change(request, obj)

    Determines the :class:`~django.http.HttpResponse` for the

    :meth:`change_view` stage.

    ``response_change`` is called after the admin form is submitted and

    just after the object and all the related instances have

    been saved. You can override it to change the default

    behavior after the object has been changed.

.. method:: ModelAdmin.response_delete(request, obj_display, obj_id)

    Determines the :class:`~django.http.HttpResponse` for the

    :meth:`delete_view` stage.

    ``response_delete`` is called after the object has been

    deleted. You can override it to change the default

    behavior after the object has been deleted.

    ``obj_display`` is a string with the name of the deleted

    object.

    ``obj_id`` is the serialized identifier used to retrieve the object to be

    deleted.

.. method:: ModelAdmin.get_formset_kwargs(request, obj, inline, prefix)

    .. versionadded:: 4.0

    A hook for customizing the keyword arguments passed to the constructor of a

    formset. For example, to pass ``request`` to formset forms::

        class MyModelAdmin(admin.ModelAdmin):

            def get_formset_kwargs(self, request, obj, inline, prefix):

                return {

                    **super().get_formset_kwargs(request, obj, inline, prefix),

                    'form_kwargs': {'request': request},

                }

    You can also use it to set ``initial`` for formset forms.

.. method:: ModelAdmin.get_changeform_initial_data(request)

    A hook for the initial data on admin change forms. By default, fields are

    given initial values from ``GET`` parameters. For instance,

    ``?name=initial_value`` will set the ``name`` field's initial value to be

    ``initial_value``.

    This method should return a dictionary in the form

    ``{'fieldname': 'fieldval'}``::

        def get_changeform_initial_data(self, request):

            return {'name': 'custom_initial_value'}

.. method:: ModelAdmin.get_deleted_objects(objs, request)

    A hook for customizing the deletion process of the :meth:`delete_view` and

    the "delete selected" :doc:`action <actions>`.

    The ``objs`` argument is a homogeneous iterable of objects (a ``QuerySet``

    or a list of model instances) to be deleted, and ``request`` is the

    :class:`~django.http.HttpRequest`.

    This method must return a 4-tuple of

    ``(deleted_objects, model_count, perms_needed, protected)``.

    ``deleted_objects`` is a list of strings representing all the objects that

    will be deleted. If there are any related objects to be deleted, the list

    is nested and includes those related objects. The list is formatted in the

    template using the :tfilter:`unordered_list` filter.

    ``model_count`` is a dictionary mapping each model's

    :attr:`~django.db.models.Options.verbose_name_plural` to the number of

    objects that will be deleted.

    ``perms_needed`` is a set of :attr:`~django.db.models.Options.verbose_name`\s

    of the models that the user doesn't have permission to delete.

    ``protected`` is a list of strings representing of all the protected

    related objects that can't be deleted. The list is displayed in the

    template.

Other methods

~~~~~~~~~~~~~

.. method:: ModelAdmin.add_view(request, form_url='', extra_context=None)

    Django view for the model instance addition page. See note below.

.. method:: ModelAdmin.change_view(request, object_id, form_url='', extra_context=None)

    Django view for the model instance editing page. See note below.

.. method:: ModelAdmin.changelist_view(request, extra_context=None)

    Django view for the model instances change list/actions page. See note

    below.

.. method:: ModelAdmin.delete_view(request, object_id, extra_context=None)