The Django admin site

One of the most powerful parts of Django is the automatic admin interface. Itreads metadata from your models to provide a quick, model-centric interfacewhere trusted users can manage content on your site. The admin's recommendeduse is limited to an organization's internal management tool. It's not intendedfor building your entire front end around.

The admin has many hooks for customization, but beware of trying to use thosehooks exclusively. If you need to provide a more process-centric interfacethat 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 admininterface.

Overview

The admin is enabled in the default project template used bystartproject.

For reference, here are the requirements:

• Add 'django.contrib.admin' to your INSTALLED_APPS setting.
• The admin has four dependencies - django.contrib.auth,django.contrib.contenttypes,django.contrib.messages anddjango.contrib.sessions. If these applications are notin your INSTALLED_APPS list, add them.
• Add django.contrib.auth.context_processors.auth anddjango.contrib.messages.context_processors.messages tothe 'context_processors' option of the DjangoTemplates backenddefined in your TEMPLATES as well asdjango.contrib.auth.middleware.AuthenticationMiddleware anddjango.contrib.messages.middleware.MessageMiddleware toMIDDLEWARE. These are all active by default, so you only need todo this if you've manually tweaked the settings.
• Determine which of your application's models should be editable in theadmin interface.
• For each of those models, optionally create a ModelAdmin class thatencapsulates the customized admin functionality and options for thatparticular model.
• Instantiate an AdminSite and tell it about each of your models andModelAdmin classes.
• Hook the AdminSite instance into your URLconf.After you've taken these steps, you'll be able to use your Django admin siteby visiting the URL you hooked it into (/admin/, by default). If you needto create a user to login with, you can use the createsuperusercommand.

Other topics

• Admin actions
• The Django admin documentation generator
• JavaScript customizations in the admin

See also

For information about serving the static files (images, JavaScript, andCSS) associated with the admin in production, see Serving files.

Having problems? Try FAQ: 管理.

ModelAdmin objects

• class ModelAdmin[source]
• The ModelAdmin class is the representation of a model in the admininterface. Usually, these are stored in a file named admin.py in yourapplication. Let's take a look at a very simple example ofthe ModelAdmin:

from django.contrib import admin
from myproject.myapp.models import Author
 
class AuthorAdmin(admin.ModelAdmin):
    pass
admin.site.register(Author, AuthorAdmin)

Do you need a ModelAdmin object at all?

In the preceding example, the ModelAdmin class doesn't define anycustom values (yet). As a result, the default admin interface will beprovided. If you are happy with the default admin interface, you don'tneed to define a ModelAdmin object at all — you can register themodel class without providing a ModelAdmin description. Thepreceding example could be simplified to:

from django.contrib import admin
from myproject.myapp.models import Author
 
admin.site.register(Author)

The register decorator

• register(*models, site=django.admin.sites.site)[source]
• 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 AdminSite, pass it using the site keywordargument:

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 adminclass in its init() method, e.g.super(PersonAdmin, self).init(args, **kwargs). You can usesuper().init(args, **kwargs).

Discovery of admin files

When you put 'django.contrib.admin' in your INSTALLED_APPSsetting, Django automatically looks for an admin module in eachapplication and imports it.

• class apps.AdminConfig

• This is the default AppConfig class for the admin.It calls autodiscover() when Django starts.

• class apps.SimpleAdminConfig

• This class works like AdminConfig,except it doesn't call autodiscover().

• autodiscover()[source]

• This function attempts to import an admin module in each installedapplication. Such modules are expected to register models with the admin.

Typically you won't need to call this function directly asAdminConfig calls it when Django starts.

If you are using a custom AdminSite, it is common to import all of theModelAdmin subclasses into your code and register them to the customAdminSite. In that case, in order to disable auto-discovery, you shouldput 'django.contrib.admin.apps.SimpleAdminConfig' instead of'django.contrib.admin' in your INSTALLED_APPS setting.

ModelAdmin options

The ModelAdmin is very flexible. It has several options for dealing withcustomizing the interface. All options are defined on the ModelAdminsubclass:

from django.contrib import admin
 
class AuthorAdmin(admin.ModelAdmin):
    date_hierarchy = 'pub_date'

• ModelAdmin.actions

• A list of actions to make available on the change list page. SeeAdmin actions for details.

• ModelAdmin.actions_on_top

• ModelAdmin.actions_on_bottom

• Controls where on the page the actions bar appears. By default, the adminchangelist displays actions at the top of the page (actions_on_top = True;actions_on_bottom = False).

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

• ModelAdmin.date_hierarchy

• Set date_hierarchy to the name of a DateField or DateTimeFieldin your model, and the change list page will include a date-based drilldownnavigation 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-leveldrill-down only.

Changed in Django 1.11:The ability to reference fields on related models was added.

Note

date_hierarchy uses QuerySet.datetimes() internally. Please referto its documentation for some caveats when time zone support isenabled (USE_TZ = True).

• ModelAdmin.empty_value_display
• This attribute overrides the default display value for record's fields thatare empty (None, empty string, etc.). The default value is - (adash). 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 withAdminSite.empty_value_display, or for specific fields like this:

from django.contrib import admin
 
class AuthorAdmin(admin.ModelAdmin):
    fields = ('name', 'title', 'view_birth_date')
 
    def view_birth_date(self, obj):
        return obj.birth_date
 
    view_birth_date.empty_value_display = '???'

• ModelAdmin.exclude
• This attribute, if given, should be a list of field names to exclude fromthe 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 nameand title fields, you would specify fields or exclude likethis:

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, andbirth_date, the forms resulting from the above declarations willcontain exactly the same fields.

• ModelAdmin.fields
• Use the fields option to make simple layout changes in the forms onthe "add" and "change" pages such as showing only a subset of availablefields, modifying their order, or grouping them into rows. For example, youcould define a simpler version of the admin form for thedjango.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 contentwill be displayed, sequentially, in the form. fields can containvalues defined in ModelAdmin.readonly_fields to be displayed asread-only.

For more complex layout needs, see the fieldsets option.

The fields option, unlike list_display, may onlycontain names of fields on the model or the form specified byform. It may contain callables only if they are listedin readonly_fields.

To display multiple fields on the same line, wrap those fields in their owntuple. In this example, the url and title fields will display on thesame line and the content field will be displayed below them on itsown line:

class FlatPageAdmin(admin.ModelAdmin):
    fields = (('url', 'title'), 'content')

Note

This fields option should not be confused with the fieldsdictionary key that is within the fieldsets option,as described in the next section.

If neither fields nor fieldsets options are present,Django will default to displaying each field that isn't an AutoField andhas editable=True, in a single fieldset, in the same order as the fieldsare defined in the model.

• 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" ofthe form.)

The two-tuples are in the format (name, field_options), where nameis a string representing the title of the fieldset and field_options isa dictionary of information about the fieldset, including a list of fieldsto be displayed in it.

A full example, taken from thedjango.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:If neither fieldsets nor fields options are present,Django will default to displaying each field that isn't an AutoField andhas editable=True, in a single fieldset, in the same order as the fieldsare 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 isrequired.

Example:

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

As with the fields option, to display multiplefields on the same line, wrap those fields in their own tuple. In thisexample, the first_name and last_name fields will display onthe same line:

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

fields can contain values defined inreadonly_fields to be displayed as read-only.

If you add the name of a callable to fields, the same rule appliesas with the fields option: the callable must belisted in 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 arecollapse and wide. Fieldsets with the collapse stylewill be initially collapsed in the admin and replaced with a small"click to expand" link. Fieldsets with the wide style will begiven extra horizontal space.

• • description
  • A string of optional extra text to be displayed at the top of eachfieldset, under the heading of the fieldset. This string is notrendered for TabularInline due to itslayout.

Note that this value is not HTML-escaped when it's displayed inthe admin interface. This lets you include HTML if you so desire.Alternatively you can use plain text anddjango.utils.html.escape() to escape any HTML specialcharacters.

• ModelAdmin.filter_horizontal

• By default, a ManyToManyField is displayed inthe admin site with a <select multiple>. However, multiple-select boxescan be difficult to use when selecting many items. Adding aManyToManyField to this list will instead usea nifty unobtrusive JavaScript "filter" interface that allows searchingwithin the options. The unselected and selected options appear in two boxesside by side. See filter_vertical to use a verticalinterface.

• ModelAdmin.filter_vertical

• Same as filter_horizontal, but uses a vertical displayof the filter interface with the box of unselected options appearing abovethe box of selected options.

• ModelAdmin.form

• By default a ModelForm is dynamically created for your model. It isused to create the form presented on both the add/change pages. You caneasily provide your own ModelForm to override any default form behavioron the add/change pages. Alternatively, you can customize the defaultform rather than specifying an entirely new one by using theModelAdmin.get_form() method.

For an example see the section Adding custom validation to the admin.

Note

If you define the Meta.model attribute on aModelForm, you must also define theMeta.fields attribute (or the Meta.exclude attribute). However,since the admin has its own way of defining fields, the Meta.fieldsattribute will be ignored.

If the ModelForm is only going to be used for the admin, the easiestsolution is to omit the Meta.model attribute, since ModelAdminwill provide the correct model to use. Alternatively, you can setfields = [] in the Meta class to satisfy the validation on theModelForm.

Note

If your ModelForm and ModelAdmin both define an excludeoption 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.

• ModelAdmin.formfield_overrides
• This provides a quick-and-dirty way to override some of theField options for use in the admin.formfield_overrides is a dictionary mapping a field class to a dict ofarguments to pass to the field at construction time.

Since that's a bit abstract, let's look at a concrete example. The mostcommon use of formfield_overrides is to add a custom widget for acertain type of field. So, imagine we've written a RichTextEditorWidgetthat 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 astring. The value is another dictionary; these arguments will be passed tothe form field's init() method. See The Forms API fordetails.

Warning

If you want to use a custom widget with a relation field (i.e.ForeignKey orManyToManyField), make sure you haven'tincluded that field's name in raw_id_fields, radio_fields, orautocomplete_fields.

formfield_overrides won't let you change the widget on relationfields that have raw_id_fields, radio_fields, orautocomplete_fields set. That's because raw_id_fields,radio_fields, and autocomplete_fields imply custom widgets oftheir own.

• ModelAdmin.inlines

• See InlineModelAdmin objects below as well asModelAdmin.get_formsets_with_inlines().

• ModelAdmin.list_display

• Set list_display to control which fields are displayed on the changelist page of the admin.

Example:

list_display = ('first_name', 'last_name')

If you don't set listdisplay, the admin site will display a singlecolumn that displays the _str() 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. Forexample:

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. Thisbehaves 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 almostthe same as the callable, but self in this context is the modelinstance. Here's a full model example:

from django.contrib import admin
from django.db import models
 
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 thestr() of the related object.

• ManyToManyField fields aren't supported, because that wouldentail 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 moreon custom methods in list_display.)

• If the field is a BooleanField or NullBooleanField, Djangowill display a pretty "on" or "off" icon instead of True orFalse.

• If the string given is a method of the model, ModelAdmin or acallable, Django will HTML-escape the output by default. To escapeuser input and allow your own unescaped tags, useformat_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)
 
    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, amodel method, or a ModelAdmin method, you can customize the column'stitle by adding a short_description attribute to the callable.

• If the value of a field is None, an empty string, or an iterablewithout elements, Django will display - (a dash). You can overridethis with AdminSite.empty_value_display:

from django.contrib import admin
 
admin.site.empty_value_display = '(None)'

You can also use 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')
 
    def birth_date_view(self, obj):
         return obj.birth_date
 
    birth_date_view.empty_value_display = 'unknown'

• If the string given is a method of the model, ModelAdmin or acallable that returns True or False Django will display a pretty"on" or "off" icon if you give the method a boolean attributewhose value is True.

Here's a full example model:

from django.contrib import admin
from django.db import models
 
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() method is just as valid in list_display as anyother 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 databasefields can't be used in sorting (because Django does all the sortingat the database level).

However, if an element of list_display represents a certaindatabase field, you can indicate this fact by setting theadmin_order_field attribute of the item.

For example:

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)
 
    def colored_first_name(self):
        return format_html(
            '<span style="color: #{};">{}</span>',
            self.color_code,
            self.first_name,
        )
 
    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 whentrying to sort by colored_first_name in the admin.

To indicate descending order with admin_order_field you can use ahyphen prefix on the field name. Using the above example, this wouldlook like:

colored_first_name.admin_order_field = '-first_name'

admin_order_field supports query lookups to sort by values on relatedmodels. This example includes an "author first name" column in the listdisplay 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')
 
    def author_first_name(self, obj):
        return obj.author.first_name
 
    author_first_name.admin_order_field = 'author__first_name'

• Elements of list_display can also be properties. Please note however,that due to the way properties work in Python, settingshort_description on a property is only possible when using theproperty() function and not with the @property decorator.

For example:

class Person(models.Model):
    first_name = models.CharField(max_length=50)
    last_name = models.CharField(max_length=50)
 
    def my_property(self):
        return self.first_name + ' ' + self.last_name
    my_property.short_description = "Full name of the person"
 
    full_name = property(my_property)
 
class PersonAdmin(admin.ModelAdmin):
    list_display = ('full_name',)

• The field names in list_display will also appear as CSS classes inthe 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 thisorder:

  • 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 andas a ModelAdmin attribute, the model field will be used.

• ModelAdmin.list_display_links
• Use list_display_links to control if and which fields inlist_display should be linked to the "change" page for an object.

By default, the change list page will link the first column — the firstfield 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 aslist_display) whose columns you want converted to links.

You can specify one or many fields. As long as the fields appear inlist_display, Django doesn't care how many (or how few) fields arelinked. The only requirement is that if you want to uselist_display_links in this fashion, you must define list_display.

In this example, the first_name and last_name fields will belinked 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

• ModelAdmin.list_editable
• Set list_editable to a list of field names on the model which willallow editing on the change list page. That is, fields listed inlist_editable will be displayed as form widgets on the change listpage, allowing users to edit and save multiple rows at once.

Note

list_editable interacts with a couple of other options inparticular 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 andlist_display_links — a field can't be both a form anda link.You'll get a validation error if either of these rules are broken.

• ModelAdmin.list_filter

• Set list_filter to activate filters in the right sidebar of the changelist page of the admin, as illustrated in the following screenshot:list_filter should be a list or tuple of elements, where each elementshould be of one of the following types:

  • a field name, where the specified field should be either aBooleanField, CharField, DateField, DateTimeField,IntegerField, ForeignKey or ManyToManyField, for example:

class PersonAdmin(admin.ModelAdmin):
    list_filter = ('is_staff', 'company')

Field names in listfilter can also span relationsusing the _ lookup, for example:

class PersonAdmin(admin.UserAdmin):
    list_filter = ('company__name',)

• a class inheriting from django.contrib.admin.SimpleListFilter,which you need to provide the title and parameter_nameattributes to and override the lookups and queryset methods,e.g.:

from datetime import date
 
from django.contrib import admin
from django.utils.translation import gettext_lazy as _
 
class DecadeBornListFilter(admin.SimpleListFilter):
    # Human-readable title which will be displayed in the
    # right admin sidebar just above the filter options.
    title = _('decade born')
 
    # Parameter for the filter that will be used in the URL query.
    parameter_name = 'decade'
 
    def lookups(self, request, model_admin):
        """
        Returns a list of tuples. The first element in each
        tuple is the coded value for the option that will
        appear in the URL query. The second element is the
        human-readable name for the option that will appear
        in the right sidebar.
        """
        return (
            ('80s', _('in the eighties')),
            ('90s', _('in the nineties')),
        )
 
    def queryset(self, request, queryset):
        """
        Returns the filtered queryset based on the value
        provided in the query string and retrievable via
        `self.value()`.
        """
        # Compare the requested value (either '80s' or '90s')
        # to decide how to filter the queryset.
        if self.value() == '80s':
            return queryset.filter(birthday__gte=date(1980, 1, 1),
                                    birthday__lte=date(1989, 12, 31))
        if self.value() == '90s':
            return queryset.filter(birthday__gte=date(1990, 1, 1),
                                    birthday__lte=date(1999, 12, 31))
 
class PersonAdmin(admin.ModelAdmin):
    list_filter = (DecadeBornListFilter,)

Note

As a convenience, the HttpRequest object is passed to thelookups and queryset methods, for example:

class AuthDecadeBornListFilter(DecadeBornListFilter):
 
    def lookups(self, request, model_admin):
        if request.user.is_superuser:
            return super().lookups(request, model_admin)
 
    def queryset(self, request, queryset):
        if request.user.is_superuser:
            return super().queryset(request, queryset)

Also as a convenience, the ModelAdmin object is passed tothe lookups method, for example if you want to base thelookups on the available data:

class AdvancedDecadeBornListFilter(DecadeBornListFilter):
 
    def lookups(self, request, model_admin):
        """
        Only show the lookups if there actually is
        anyone born in the corresponding decades.
        """
        qs = model_admin.get_queryset(request)
        if qs.filter(birthday__gte=date(1980, 1, 1),
                      birthday__lte=date(1989, 12, 31)).exists():
            yield ('80s', _('in the eighties'))
        if qs.filter(birthday__gte=date(1990, 1, 1),
                      birthday__lte=date(1999, 12, 31)).exists():
            yield ('90s', _('in the nineties'))

• a tuple, where the first element is a field name and the secondelement is a class inheriting fromdjango.contrib.admin.FieldListFilter, for example:

class PersonAdmin(admin.ModelAdmin):
    list_filter = (
        ('is_staff', admin.BooleanFieldListFilter),
    )

You can limit the choices of a related model to the objects involved inthat relation using RelatedOnlyFieldListFilter:

class BookAdmin(admin.ModelAdmin):
    list_filter = (
        ('author', admin.RelatedOnlyFieldListFilter),
    )

Assuming author is a ForeignKey to a User model, this willlimit the list_filter choices to the users who have written a bookinstead of listing all users.

Note

The FieldListFilter API is considered internal and might bechanged.

List filter's typically appear only if the filter has more than one choice.A filter's has_output() method controls whether or not it appears.

It is possible to specify a custom template for rendering a list filter:

class FilterWithCustomTemplate(admin.SimpleListFilter):
    template = "custom_template.html"

See the default template provided by Django (admin/filter.html) fora concrete example.

• ModelAdmin.list_max_show_all

• Set list_max_show_all to control how many items can appear on a "Showall" admin change list page. The admin will display a "Show all" link on thechange list only if the total result count is less than or equal to thissetting. By default, this is set to 200.

• ModelAdmin.list_per_page

• Set list_per_page to control how many items appear on each paginatedadmin change list page. By default, this is set to 100.

• ModelAdmin.list_select_related

• Set list_select_related to tell Django to useselect_related() in retrievingthe list of objects on the admin change list page. This can save you abunch of database queries.

The value should be either a boolean, a list or a tuple. Default isFalse.

When value is True, select_related() will always be called. Whenvalue is set to False, Django will look at list_display and callselect_related() if any ForeignKey is present.

If you need more fine-grained control, use a tuple (or list) as value forlist_select_related. Empty tuple will prevent Django from callingselect_related at all. Any other tuple will be passed directly toselect_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 canimplement a get_list_select_related() method.

• ModelAdmin.ordering
• Set ordering to specify how lists of objects should be ordered in theDjango admin views. This should be a list or tuple in the same format as amodel's ordering parameter.

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

If you need to specify a dynamic order (for example depending on user orlanguage) you can implement a get_ordering() method.

• ModelAdmin.paginator

• The paginator class to be used for pagination. By default,django.core.paginator.Paginator is used. If the custom paginatorclass doesn't have the same constructor interface asdjango.core.paginator.Paginator, you will also need toprovide an implementation for ModelAdmin.get_paginator().

• ModelAdmin.prepopulated_fields

• Set prepopulated_fields to a dictionary mapping field names to thefields 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 fromthe fields assigned. The main use for this functionality is toautomatically generate the value for SlugField fields from one or moreother fields. The generated value is produced by concatenating the valuesof the source fields, and then by transforming that result into a validslug (e.g. substituting dashes for spaces; lowercasing ASCII letters; andremoving various English stop words such as 'a', 'an', 'as', and similar).

Fields are prepopulated on add forms but not on change forms. It's usuallyundesired that slugs change after an object is created (which would causean object's URL to change if the slug is used in it).

prepopulated_fields doesn't accept DateTimeField, ForeignKey,OneToOneField, and ManyToManyField fields.

• ModelAdmin.preserve_filters

• The admin now preserves filters on the list view after creating, editingor deleting an object. You can restore the previous behavior of clearingfilters by setting this attribute to False.

• ModelAdmin.radio_fields

• By default, Django's admin uses a select-box interface () forfields that are ForeignKey or have choices set. If a field ispresent in radio_fields, Django will use a radio-button interfaceinstead. 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 thedjango.contrib.admin module. Don't include a field in radio_fields unless it's a ForeignKey or haschoices set.
  • ModelAdmin.autocomplete_fields
  • New in Django 2.0.

  autocomplete_fields is a list of ForeignKey and/orManyToManyField fields you would like to change to Select2 autocomplete inputs.

  By default, the admin uses a select-box interface (<select>) forthose fields. Sometimes you don't want to incur the overhead of selectingall the related instances to display in the dropdown.

  The Select2 input looks similar to the default input but comes with asearch feature that loads the options asynchronously. This is faster andmore user-friendly if the related model has many instances.

  You must define search_fields on the related object'sModelAdmin because the autocomplete search uses it.

  Ordering and pagination of the results are controlled by the relatedModelAdmin's get_ordering() andget_paginator() methods.

  In the following example, ChoiceAdmin has an autocomplete field for theForeignKey to the Question. The results are filtered by thequestion_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']

  Performance considerations for large datasets

  Ordering using ModelAdmin.ordering may cause performanceproblems as sorting on a large queryset will be slow.

  Also, if your search fields include fields that aren't indexed by thedatabase, you might encounter poor performance on extremely largetables.

  For those cases, it's a good idea to write your ownModelAdmin.get_search_results() implementation using afull-text indexed search.

  You may also want to change the Paginator on very large tablesas the default paginator always performs a count() query.For example, you could override the default implementation of thePaginator.count property.

  • ModelAdmin.raw_id_fields
  • By default, Django's admin uses a select-box interface () forfields that are ForeignKey. Sometimes you don't want to incur theoverhead of having to select all the related instances to display in thedrop-down. raw_id_fields is a list of fields you would like to changeinto an Input widget for either a ForeignKey orManyToManyField: class ArticleAdmin(admin.ModelAdmin): raw_id_fields = ("newspaper",) The raw_id_fields Input widget should contain a primary key if thefield is a ForeignKey or a comma separated list of values if the fieldis a ManyToManyField. The raw_id_fields widget shows a magnifyingglass button next to the field which allows users to search for and selecta value:
    • ModelAdmin.readonly_fields
    • By default the admin shows all fields as editable. Any fields in thisoption (which should be a list or tuple) will display its dataas-is and non-editable; they are also excluded from theModelForm used for creating and editing. Note thatwhen specifying ModelAdmin.fields or ModelAdmin.fieldsetsthe read-only fields must be present to be shown (they are ignoredotherwise).

    If readonly_fields is used without defining explicit ordering throughModelAdmin.fields or ModelAdmin.fieldsets they will beadded last after all editable fields.

    A read-only field can not only display data from a model's field, it canalso display the output of a model's method or a method of theModelAdmin class itself. This is very similar to the wayModelAdmin.list_display behaves. This provides an easy way to usethe admin interface to provide feedback on the status of the objects beingedited, 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',)
     
        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>")
     
        # short_description functions like a model field's verbose_name
        address_report.short_description = "Address"

    • 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 continueediting", and "Save and add another". If save_as is True, "Saveand add another" will be replaced by a "Save as new" button that creates anew object (with a new ID) rather than updating the existing object.

    By default, save_as is set to False.

    • ModelAdmin.save_as_continue
    • When save_as=True, the default redirect after saving thenew object is to the change view for that object. If you setsave_as_continue=False, the redirect will be to the changelist view.

    By default, save_as_continue is set to True.

    • ModelAdmin.save_on_top
    • Set save_on_top to add save buttons across the top of your admin changeforms.

    Normally, the save buttons appear only at the bottom of the forms. If youset save_on_top, the buttons will appear both on the top and thebottom.

    By default, save_on_top is set to False.

    • 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 wheneversomebody submits a search query in that text box.

    These fields should be some kind of text field, such as CharField orTextField. You can also perform a related lookup on a ForeignKey orManyToManyField with the lookup API "follow" notation:

    search_fields = ['foreign_key__related_fieldname']

    For example, if you have a blog entry with an author, the followingdefinition would enable searching blog entries by the email address of theauthor:

    search_fields = ['user__email']

    When somebody does a search in the admin search box, Django splits thesearch query into words and returns all objects that contain each of thewords, case insensitive, where each word must be in at least one ofsearch_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:

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

    For faster and/or more restrictive searches, prefix the field namewith an operator:

    • ^
    • Use the '^' operator to match starting at the beginning of thefield. For example, if search_fields is set to['^first_name', '^last_name'] and a user searches forjohn lennon, Django will do the equivalent of this SQL WHEREclause:

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

    This query is more efficient than the normal '%john%' query,because the database only needs to check the beginning of a column'sdata, rather than seeking through the entire column's data. Plus, ifthe column has an index on it, some databases may be able to use theindex for this query, even though it's a LIKE query.

    • =
    • Use the '=' operator for case-insensitive exact matching. Forexample, if search_fields is set to['=first_name', '=last_name'] and a user searches forjohn lennon, Django will do the equivalent of this SQLWHERE clause:

    WHERE (first_name ILIKE 'john' OR last_name ILIKE 'john')
    AND (first_name ILIKE 'lennon' OR last_name ILIKE 'lennon')

    Note that the query input is split by spaces, so, following thisexample, it's currently not possible to search for all records in whichfirst_name is exactly 'john winston' (containing a space).

    • @
    • Using the '@' operator to perform a full text match. This is like thedefault search method but uses an index. Currently this is onlyavailable for MySQL.If you need to customize search you can useModelAdmin.get_search_results() to provide additional or alternatesearch behavior.
    • ModelAdmin.show_full_result_count
    • Set show_full_result_count to control whether the full count of objectsshould 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 performa full count on the table which can be expensive if the table contains alarge number of rows.

    • 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 (thedefault), the object's get_absolute_url()method will be used to generate the url.

    If your model has a get_absolute_url() methodbut you don't want the "View on site" button to appear, you only need to setview_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 Overriding admin templates section describes how to override or extendthe default admin templates. Use the following options to override the defaulttemplates used by the ModelAdmin views:

    • ModelAdmin.add_form_template

    • Path to a custom template, used by add_view().

    • ModelAdmin.change_form_template

    • Path to a custom template, used by change_view().

    • ModelAdmin.change_list_template

    • Path to a custom template, used by changelist_view().

    • ModelAdmin.delete_confirmation_template

    • Path to a custom template, used by delete_view() for displaying aconfirmation page when deleting one or more objects.

    • ModelAdmin.delete_selected_confirmation_template

    • Path to a custom template, used by the delete_selected action methodfor displaying a confirmation page when deleting one or more objects. Seethe actions documentation.

    • ModelAdmin.object_history_template

    • Path to a custom template, used by history_view().

    • ModelAdmin.popup_response_template

    • New in Django 1.11.

    Path to a custom template, used by response_add(),response_change(), and response_delete().

    ModelAdmin methods

    Warning

    When overriding ModelAdmin.save_model() andModelAdmin.delete_model(), your code must save/delete theobject. They aren't meant for veto purposes, rather they allow you toperform extra operations.

    • ModelAdmin.savemodel(_request, obj, form, change)[source]
    • The save_model method is given the HttpRequest, a model instance,a ModelForm instance, and a boolean value based on whether it is addingor changing the object. Overriding this method allows doing pre- orpost-save operations. Call super().save_model() to save the objectusing 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)

    • ModelAdmin.deletemodel(_request, obj)[source]

    • The delete_model method is given the HttpRequest and a modelinstance. Overriding this method allows doing pre- or post-deleteoperations. Call super().delete_model() to delete the object usingModel.delete().

    • ModelAdmin.saveformset(_request, form, formset, change)[source]

    • The save_formset method is given the HttpRequest, the parentModelForm instance and a boolean value based on whether it is adding orchanging the parent object.

    For example, to attach request.user to each changed formsetmodel 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 Saving objects in the formset.

    • ModelAdmin.getordering(_request)
    • The get_ordering method takes a request as parameter andis expected to return a list or tuple for ordering similarto the ordering attribute. For example:

    class PersonAdmin(admin.ModelAdmin):
     
        def get_ordering(self, request):
            if request.user.is_superuser:
                return ['name', 'rank']
            else:
                return ['name']

    • ModelAdmin.getsearch_results(_request, queryset, search_term)[source]
    • The get_search_results method modifies the list of objects displayedinto those that match the provided search term. It accepts the request, aqueryset that applies the current filters, and the user-provided search term.It returns a tuple containing a queryset modified to implement the search, anda boolean indicating if the results may contain duplicates.

    The default implementation searches the fields named in ModelAdmin.search_fields.

    This method may be overridden with your own custom search method. Forexample, you might wish to search by an integer field, or use an externaltool such as Solr or Haystack. You must establish if the queryset changesimplemented 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, use_distinct = 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, use_distinct

    This implementation is more efficient than search_fields =('name', '=age') which results in a string comparison for the numericfield, for example … OR UPPER("polls_choice"."votes"::text) = UPPER('4')on PostgreSQL.

    • ModelAdmin.saverelated(_request, form, formsets, change)[source]

    • The save_related method is given the HttpRequest, the parentModelForm instance, the list of inline formsets and a boolean valuebased on whether the parent is being added or changed. Here you can do anypre- or post-save operations for objects related to the parent. Notethat at this point the parent object and its form have already been saved.

    • ModelAdmin.getautocomplete_fields(_request)

    • New in Django 2.0.

    The get_autocomplete_fields() method is given the HttpRequest and isexpected to return a list or tuple of field names that will bedisplayed with an autocomplete widget as described above in theModelAdmin.autocomplete_fields section.

    • ModelAdmin.getreadonly_fields(_request, obj=None)

    • The get_readonly_fields method is given the HttpRequest and theobj being edited (or None on an add form) and is expected to returna list or tuple of field names that will be displayed as read-only,as described above in the ModelAdmin.readonly_fields section.

    • ModelAdmin.getprepopulated_fields(_request, obj=None)

    • The get_prepopulated_fields method is given the HttpRequest and theobj being edited (or None on an add form) and is expected to returna dictionary, as described above in the ModelAdmin.prepopulated_fieldssection.

    • ModelAdmin.getlist_display(_request)[source]

    • The get_list_display method is given the HttpRequest and isexpected to return a list or tuple of field names that will bedisplayed on the changelist view as described above in theModelAdmin.list_display section.

    • ModelAdmin.getlist_display_links(_request, list_display)[source]

    • The get_list_display_links method is given the HttpRequest andthe list or tuple returned by ModelAdmin.get_list_display().It is expected to return either None or a list or tuple of fieldnames on the changelist that will be linked to the change view, as describedin the ModelAdmin.list_display_links section.

    • ModelAdmin.getexclude(_request, obj=None)

    • New in Django 1.11.

    The get_exclude method is given the HttpRequest and the objbeing edited (or None on an add form) and is expected to return a listof fields, as described in ModelAdmin.exclude.

    • ModelAdmin.getfields(_request, obj=None)

    • The get_fields method is given the HttpRequest and the objbeing edited (or None on an add form) and is expected to return a listof fields, as described above in the ModelAdmin.fields section.

    • ModelAdmin.getfieldsets(_request, obj=None)

    • The get_fieldsets method is given the HttpRequest and the objbeing edited (or None on an add form) and is expected to return a listof two-tuples, in which each two-tuple represents a <fieldset> on theadmin form page, as described above in the ModelAdmin.fieldsets section.

    • ModelAdmin.getlist_filter(_request)[source]

    • The get_list_filter method is given the HttpRequest and is expectedto return the same kind of sequence type as for thelist_filter attribute.

    • ModelAdmin.getlist_select_related(_request)[source]

    • The get_list_select_related method is given the HttpRequest andshould return a boolean or list as ModelAdmin.list_select_relateddoes.

    • ModelAdmin.getsearch_fields(_request)[source]

    • The get_search_fields method is given the HttpRequest and is expectedto return the same kind of sequence type as for thesearch_fields attribute.

    • ModelAdmin.getinline_instances(_request, obj=None)[source]

    • The get_inline_instances method is given the HttpRequest and theobj being edited (or None on an add form) and is expected to returna list or tuple of InlineModelAdminobjects, as described below in the InlineModelAdminsection. For example, the following would return inlines without the defaultfiltering based on add, change, and delete 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 areinstances of the classes defined in inlines or you might encountera "Bad Request" error when adding related objects.

    • ModelAdmin.get_urls()[source]
    • The get_urls method on a ModelAdmin returns the URLs to be used forthat ModelAdmin in the same way as a URLconf. Therefore you can extendthem as documented in URL调度器:

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

    {% extends "admin/base_site.html" %}
    {% block content %}
    ...
    {% endblock %}

    Note

    Notice that the custom patterns are included before the regular adminURLs: the admin URL patterns are very permissive and will match nearlyanything, so you'll usually want to prepend your custom URLs to thebuilt-in ones.

    In this example, my_view will be accessed at/admin/myapp/mymodel/my_view/ (assuming the admin URLs are includedat /admin/.)

    However, the self.my_view function registered above suffers from twoproblems:

    • It will not perform any permission checks, so it will be accessibleto the general public.
    • It will not provide any header details to prevent caching. This meansif the page retrieves data from the database, and caching middleware isactive, the page could show outdated information.Since this is usually not what you want, Django provides a conveniencewrapper to check permissions and mark the view as non-cacheable. Thiswrapper is AdminSite.admin_view() (i.e. self.admin_site.admin_viewinside a ModelAdmin instance); use it like so:

    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

    Notice the wrapped view in the fifth line above:

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

    This wrapping will protect self.my_view from unauthorized access andwill apply the django.views.decorators.cache.never_cache() decorator tomake sure it is not cached if the cache middleware is active.

    If the page is cacheable, but you still want the permission check to beperformed, you can pass a cacheable=True argument toAdminSite.admin_view():

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

    ModelAdmin views have model_admin attributes. OtherAdminSite views have admin_site attributes.

    • ModelAdmin.getform(_request, obj=None, **kwargs)[source]
    • Returns a ModelForm class for use in the admin addand change views, see add_view() and change_view().

    The base implementation uses modelform_factory()to subclass form, modified by attributes such as fieldsand exclude. So, for example, if you wanted to offer additionalfields 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 simply return a custom ModelForm classdirectly.

    • ModelAdmin.getformsets_with_inlines(_request, obj=None)[source]
    • Yields (FormSet, InlineModelAdmin) pairs for use in admin addand change views.

    For example if you wanted to display a particular inline only in the changeview, 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 isinstance(inline, MyInline) and obj is None:
                    continue
                yield inline.get_formset(request, obj), inline

    • ModelAdmin.formfieldfor_foreignkey(_db_field, request, **kwargs)
    • The formfield_for_foreignkey method on a ModelAdmin allows you tooverride the default formfield for a foreign keys field. For example, toreturn 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 keyfield to only display the cars owned by the User instance.

    • ModelAdmin.formfieldfor_manytomany(_db_field, request, **kwargs)
    • Like the formfield_for_foreignkey method, theformfield_for_manytomany method can be overridden to change thedefault formfield for a many to many field. For example, if an owner canown multiple cars and cars can belong to multiple owners — a many tomany relationship — you could filter the Car foreign key field toonly 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)

    • ModelAdmin.formfieldfor_choice_field(_db_field, request, **kwargs)
    • Like the formfield_for_foreignkey and formfield_for_manytomanymethods, the formfield_for_choice_field method can be overridden tochange the default formfield for a field that has declared choices. Forexample, if the choices available to a superuser should be different thanthose 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)

    Note

    Any choices attribute set on the formfield will be limited to theform field only. If the corresponding field on the model has choicesset, the choices provided to the form must be a valid subset of thosechoices, otherwise the form submission will fail witha ValidationError when the model itselfis validated before saving.

    • ModelAdmin.getchangelist(_request, **kwargs)[source]

    • Returns the Changelist class to be used for listing. By default,django.contrib.admin.views.main.ChangeList is used. By inheriting thisclass you can change the behavior of the listing.

    • ModelAdmin.getchangelist_form(_request, **kwargs)[source]

    • Returns a ModelForm class for use in the Formseton 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

    Note

    If you define the Meta.model attribute on aModelForm, you must also define theMeta.fields attribute (or the Meta.exclude attribute). However,ModelAdmin ignores this value, overriding it with theModelAdmin.list_editable attribute. The easiest solution is toomit the Meta.model attribute, since ModelAdmin will provide thecorrect model to use.

    • ModelAdmin.getchangelist_formset(_request, **kwargs)[source]
    • Returns a ModelFormSet class for use on thechangelist page if list_editable is used. To use acustom 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)

    • ModelAdmin.lookupallowed(_lookup, value)
    • The objects in the changelist page can be filtered with lookups from theURL's query string. This is how list_filter works, for example. Thelookups are similar to what's used in QuerySet.filter() (e.g.user__email=user@example.com). Since the lookups in the query stringcan be manipulated by the user, they must be sanitized to preventunauthorized 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. 'user@example.com'), and returns a boolean indicating whetherfiltering the changelist's QuerySet using the parameters is permitted.If lookup_allowed() returns False, DisallowedModelAdminLookup(subclass of SuspiciousOperation) is raised.

    By default, lookup_allowed() allows access to a model's local fields,field paths used in list_filter (but not paths fromget_list_filter()), and lookups required forlimit_choices_to to functioncorrectly in raw_id_fields.

    Override this method to customize the lookups permitted for yourModelAdmin subclass.

    • ModelAdmin.hasadd_permission(_request)

    • Should return True if adding an object is permitted, Falseotherwise.

    • ModelAdmin.haschange_permission(_request, obj=None)

    • Should return True if editing obj is permitted, Falseotherwise. If obj is None, should return True or False toindicate whether editing of objects of this type is permitted in general(e.g., False will be interpreted as meaning that the current user isnot permitted to edit any object of this type).

    • ModelAdmin.hasdelete_permission(_request, obj=None)

    • Should return True if deleting obj is permitted, Falseotherwise. If obj is None, should return True or False toindicate whether deleting objects of this type is permitted in general(e.g., False will be interpreted as meaning that the current user isnot permitted to delete any object of this type).

    • ModelAdmin.hasmodule_permission(_request)

    • Should return True if displaying the module on the admin index page andaccessing the module's index page is permitted, False otherwise.Uses User.has_module_perms() by default. Overridingit does not restrict access to the add, change or delete views,has_add_permission(),has_change_permission(), andhas_delete_permission() should be used for that.

    • ModelAdmin.getqueryset(_request)

    • The get_queryset method on a ModelAdmin returns aQuerySet of all model instances thatcan be edited by the admin site. One use case for overriding this methodis 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)

    • ModelAdmin.messageuser(_request, message, level=messages.INFO, extra_tags='', fail_silently=False)[source]
    • Sends a message to the user using the django.contrib.messagesbackend. See the custom ModelAdmin example.

    Keyword arguments allow you to change the message level, add extra CSStags, or fail silently if the contrib.messages framework is notinstalled. These keyword arguments match those fordjango.contrib.messages.add_message(), see that function'sdocumentation for more details. One difference is that the level may bepassed as a string label in addition to integer/constant.

    • ModelAdmin.getpaginator(_request, queryset, per_page, orphans=0, allow_empty_first_page=True)[source]

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

    • ModelAdmin.responseadd(_request, obj, post_url_continue=None)[source]

    • Determines the HttpResponse for theadd_view() stage.

    response_add is called after the admin form is submitted andjust after the object and all the related instances havebeen created and saved. You can override it to change the default behaviorafter the object has been created.

    • ModelAdmin.responsechange(_request, obj)[source]
    • Determines the HttpResponse for thechange_view() stage.

    response_change is called after the admin form is submitted andjust after the object and all the related instances havebeen saved. You can override it to change the defaultbehavior after the object has been changed.

    • ModelAdmin.responsedelete(_request, obj_display, obj_id)[source]
    • Determines the HttpResponse for thedelete_view() stage.

    response_delete is called after the object has beendeleted. You can override it to change the defaultbehavior after the object has been deleted.

    obj_display is a string with the name of the deletedobject.

    obj_id is the serialized identifier used to retrieve the object to bedeleted.

    • ModelAdmin.getchangeform_initial_data(_request)[source]
    • A hook for the initial data on admin change forms. By default, fields aregiven initial values from GET parameters. For instance,?name=initial_value will set the name field's initial value to beinitial_value.

    This method should return a dictionary in the form{'fieldname': 'fieldval'}:

    def get_changeform_initial_data(self, request):
        return {'name': 'custom_initial_value'}

    Other methods

    • ModelAdmin.addview(_request, form_url='', extra_context=None)[source]

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

    • ModelAdmin.changeview(_request, object_id, form_url='', extra_context=None)[source]

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

    • ModelAdmin.changelistview(_request, extra_context=None)[source]

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

    • ModelAdmin.deleteview(_request, object_id, extra_context=None)[source]

    • Django view for the model instance(s) deletion confirmation page. See notebelow.

    • ModelAdmin.historyview(_request, object_id, extra_context=None)[source]

    • Django view for the page that shows the modification history for a givenmodel instance.

    Unlike the hook-type ModelAdmin methods detailed in the previous section,these five methods are in reality designed to be invoked as Django views fromthe admin application URL dispatching handler to render the pages that dealwith model instances CRUD operations. As a result, completely overriding thesemethods will significantly change the behavior of the admin application.

    One common reason for overriding these methods is to augment the context datathat is provided to the template that renders the view. In the followingexample, the change view is overridden so that the rendered template isprovided some extra mapping data that would not otherwise be available:

    class MyModelAdmin(admin.ModelAdmin):
     
        # A template for a very customized change view:
        change_form_template = 'admin/myapp/extras/openstreetmap_change_form.html'
     
        def get_osm_info(self):
            # ...
            pass
     
        def change_view(self, request, object_id, form_url='', extra_context=None):
            extra_context = extra_context or {}
            extra_context['osm_data'] = self.get_osm_info()
            return super().change_view(
                request, object_id, form_url, extra_context=extra_context,
            )

    These views return TemplateResponseinstances which allow you to easily customize the response data beforerendering. For more details, see the TemplateResponse documentation.

    ModelAdmin asset definitions

    There are times where you would like add a bit of CSS and/or JavaScript tothe add/change views. This can be accomplished by using a Media inner classon your ModelAdmin:

    class ArticleAdmin(admin.ModelAdmin):
        class Media:
            css = {
                "all": ("my_styles.css",)
            }
            js = ("my_code.js",)

    The staticfiles app prependsSTATIC_URL (or MEDIA_URL if STATIC_URL isNone) to any asset paths. The same rules apply as regular assetdefinitions on forms.

    jQuery

    Django admin JavaScript makes use of the jQuery library.

    To avoid conflicts with user-supplied scripts or libraries, Django's jQuery(version 2.2.3) is namespaced as django.jQuery. If you want to use jQueryin your own admin JavaScript without including a second copy, you can use thedjango.jQuery object on changelist and add/edit views.

    The ModelAdmin class requires jQuery by default, so there is no needto add jQuery to your ModelAdmin’s list of media resources unless you havea specific need. For example, if you require the jQuery library to be in theglobal namespace (for example when using third-party jQuery plugins) or if youneed a newer version of jQuery, you will have to include your own copy.

    Django provides both uncompressed and 'minified' versions of jQuery, asjquery.js and jquery.min.js respectively.

    ModelAdmin and InlineModelAdmin have a media propertythat returns a list of Media objects which store paths to the JavaScriptfiles for the forms and/or formsets. If DEBUG is True it willreturn the uncompressed versions of the various JavaScript files, includingjquery.js; if not, it will return the 'minified' versions.

    Adding custom validation to the admin

    Adding custom validation of data in the admin is quite easy. The automaticadmin interface reuses django.forms, and the ModelAdmin class givesyou the ability define your own form:

    class ArticleAdmin(admin.ModelAdmin):
        form = MyArticleAdminForm

    MyArticleAdminForm can be defined anywhere as long as you import whereneeded. Now within your form you can add your own custom validation forany field:

    class MyArticleAdminForm(forms.ModelForm):
        def clean_name(self):
            # do something that validates your data
            return self.cleaned_data["name"]

    It is important you use a ModelForm here otherwise things can break. Seethe forms documentation on custom validation and, more specifically, themodel form validation notes for moreinformation.

    InlineModelAdmin objects

    • class InlineModelAdmin
    • class TabularInline[source]
    • class StackedInline[source]
    • The admin interface has the ability to edit models on the same page as aparent model. These are called inlines. Suppose you have these two models:

    from django.db import models
     
    class Author(models.Model):
       name = models.CharField(max_length=100)
     
    class Book(models.Model):
       author = models.ForeignKey(Author, on_delete=models.CASCADE)
       title = models.CharField(max_length=100)

    You can edit the books authored by an author on the author page. You addinlines to a model by specifying them in a ModelAdmin.inlines:

    from django.contrib import admin
     
    class BookInline(admin.TabularInline):
        model = Book
     
    class AuthorAdmin(admin.ModelAdmin):
        inlines = [
            BookInline,
        ]

    Django provides two subclasses of InlineModelAdmin and they are:

    • TabularInline
    • StackedInlineThe difference between these two is merely the template used to renderthem.

    InlineModelAdmin options

    InlineModelAdmin shares many of the same features as ModelAdmin, andadds some of its own (the shared features are actually defined in theBaseModelAdmin superclass). The shared features are:

    • form
    • fieldsets
    • fields
    • formfield_overrides
    • exclude
    • filter_horizontal
    • filter_vertical
    • ordering
    • prepopulated_fields
    • get_queryset()
    • radio_fields
    • readonly_fields
    • raw_id_fields
    • formfield_for_choice_field()
    • formfield_for_foreignkey()
    • formfield_for_manytomany()
    • has_add_permission()
    • has_change_permission()
    • has_delete_permission()

    • has_module_permission()The InlineModelAdmin class adds:

    • InlineModelAdmin.model

    • The model which the inline is using. This is required.

    • InlineModelAdmin.fk_name

    • The name of the foreign key on the model. In most cases this will be dealtwith automatically, but fk_name must be specified explicitly if thereare more than one foreign key to the same parent model.

    • InlineModelAdmin.formset

    • This defaults to BaseInlineFormSet. Usingyour own formset can give you many possibilities of customization. Inlinesare built around model formsets.

    • InlineModelAdmin.form

    • The value for form defaults to ModelForm. This is what is passedthrough to inlineformset_factory() whencreating the formset for this inline.

    Warning

    When writing custom validation for InlineModelAdmin forms, be cautiousof writing validation that relies on features of the parent model. If theparent model fails to validate, it may be left in an inconsistent state asdescribed in the warning in 验证 ModelForm.

    • InlineModelAdmin.classes

    • A list or tuple containing extra CSS classes to apply to the fieldset thatis rendered for the inlines. Defaults to None. As with classesconfigured in fieldsets, inlines with a collapseclass will be initially collapsed and their header will have a small "show"link.

    • InlineModelAdmin.extra

    • This controls the number of extra forms the formset will display inaddition to the initial forms. See theformsets documentation for moreinformation.

    For users with JavaScript-enabled browsers, an "Add another" link isprovided to enable any number of additional inlines to be added in additionto those provided as a result of the extra argument.

    The dynamic link will not appear if the number of currently displayed formsexceeds max_num, or if the user does not have JavaScript enabled.

    InlineModelAdmin.get_extra() also allows you to customize the numberof extra forms.

    • InlineModelAdmin.max_num
    • This controls the maximum number of forms to show in the inline. Thisdoesn't directly correlate to the number of objects, but can if the valueis small enough. See Limiting the number of editable objects for more information.

    InlineModelAdmin.get_max_num() also allows you to customize themaximum number of extra forms.

    • InlineModelAdmin.min_num
    • This controls the minimum number of forms to show in the inline.See modelformset_factory() for more information.

    InlineModelAdmin.get_min_num() also allows you to customize theminimum number of displayed forms.

    • InlineModelAdmin.raw_id_fields
    • By default, Django's admin uses a select-box interface () forfields that are ForeignKey. Sometimes you don't want to incur theoverhead of having to select all the related instances to display in thedrop-down. raw_id_fields is a list of fields you would like to change into anInput widget for either a ForeignKey or ManyToManyField: class BookInline(admin.TabularInline): model = Book raw_id_fields = ("pages",)
      • InlineModelAdmin.template

      • The template used to render the inline on the page.

      • InlineModelAdmin.verbose_name

      • An override to the verbose_name found in the model's inner Metaclass.

      • InlineModelAdmin.verbose_name_plural

      • An override to the verbose_name_plural found in the model's innerMeta class.

      • InlineModelAdmin.can_delete

      • Specifies whether or not inline objects can be deleted in the inline.Defaults to True.

      • InlineModelAdmin.show_change_link

      • Specifies whether or not inline objects that can be changed in theadmin have a link to the change form. Defaults to False.

      • InlineModelAdmin.getformset(_request, obj=None, **kwargs)

      • Returns a BaseInlineFormSet class for use inadmin add/change views. See the example forModelAdmin.get_formsets_with_inlines.

      • InlineModelAdmin.getextra(_request, obj=None, **kwargs)

      • Returns the number of extra inline forms to use. By default, returns theInlineModelAdmin.extra attribute.

      Override this method to programmatically determine the number of extrainline forms. For example, this may be based on the model instance(passed as the keyword argument obj):

      class BinaryTreeAdmin(admin.TabularInline):
          model = BinaryTree
       
          def get_extra(self, request, obj=None, **kwargs):
              extra = 2
              if obj:
                  return extra - obj.binarytree_set.count()
              return extra

      • InlineModelAdmin.getmax_num(_request, obj=None, **kwargs)
      • Returns the maximum number of extra inline forms to use. By default,returns the InlineModelAdmin.max_num attribute.

      Override this method to programmatically determine the maximum number ofinline forms. For example, this may be based on the model instance(passed as the keyword argument obj):

      class BinaryTreeAdmin(admin.TabularInline):
          model = BinaryTree
       
          def get_max_num(self, request, obj=None, **kwargs):
              max_num = 10
              if obj and obj.parent:
                  return max_num - 5
              return max_num

      • InlineModelAdmin.getmin_num(_request, obj=None, **kwargs)
      • Returns the minimum number of inline forms to use. By default,returns the InlineModelAdmin.min_num attribute.

      Override this method to programmatically determine the minimum number ofinline forms. For example, this may be based on the model instance(passed as the keyword argument obj).

      Working with a model with two or more foreign keys to the same parent model

      It is sometimes possible to have more than one foreign key to the same model.Take this model for instance:

      from django.db import models
       
      class Friendship(models.Model):
          to_person = models.ForeignKey(Person, on_delete=models.CASCADE, related_name="friends")
          from_person = models.ForeignKey(Person, on_delete=models.CASCADE, related_name="from_friends")

      If you wanted to display an inline on the Person admin add/change pagesyou need to explicitly define the foreign key since it is unable to do soautomatically:

      from django.contrib import admin
      from myapp.models import Friendship
       
      class FriendshipInline(admin.TabularInline):
          model = Friendship
          fk_name = "to_person"
       
      class PersonAdmin(admin.ModelAdmin):
          inlines = [
              FriendshipInline,
          ]

      Working with many-to-many models

      By default, admin widgets for many-to-many relations will be displayedon whichever model contains the actual reference to theManyToManyField. Depending on your ModelAdmindefinition, each many-to-many field in your model will be represented by astandard HTML <select multiple>, a horizontal or vertical filter, or araw_id_admin widget. However, it is also possible to replace thesewidgets with inlines.

      Suppose we have the following models:

      from django.db import models
       
      class Person(models.Model):
          name = models.CharField(max_length=128)
       
      class Group(models.Model):
          name = models.CharField(max_length=128)
          members = models.ManyToManyField(Person, related_name='groups')

      If you want to display many-to-many relations using an inline, you can doso by defining an InlineModelAdmin object for the relationship:

      from django.contrib import admin
       
      class MembershipInline(admin.TabularInline):
          model = Group.members.through
       
      class PersonAdmin(admin.ModelAdmin):
          inlines = [
              MembershipInline,
          ]
       
      class GroupAdmin(admin.ModelAdmin):
          inlines = [
              MembershipInline,
          ]
          exclude = ('members',)

      There are two features worth noting in this example.

      Firstly - the MembershipInline class references Group.members.through.The through attribute is a reference to the model that manages themany-to-many relation. This model is automatically created by Django when youdefine a many-to-many field.

      Secondly, the GroupAdmin must manually exclude the members field.Django displays an admin widget for a many-to-many field on the model thatdefines the relation (in this case, Group). If you want to use an inlinemodel to represent the many-to-many relationship, you must tell Django's adminto not display this widget - otherwise you will end up with two widgets onyour admin page for managing the relation.

      Note that when using this technique them2m_changed signals aren't triggered. Thisis because as far as the admin is concerned, through is just a model withtwo foreign key fields rather than a many-to-many relation.

      In all other respects, the InlineModelAdmin is exactly the same as anyother. You can customize the appearance using any of the normalModelAdmin properties.

      Working with many-to-many intermediary models

      When you specify an intermediary model using the through argument to aManyToManyField, the admin will not display awidget by default. This is because each instance of that intermediary modelrequires more information than could be displayed in a single widget, and thelayout required for multiple widgets will vary depending on the intermediatemodel.

      However, we still want to be able to edit that information inline. Fortunately,this is easy to do with inline admin models. Suppose we have the followingmodels:

      from django.db import models
       
      class Person(models.Model):
          name = models.CharField(max_length=128)
       
      class Group(models.Model):
          name = models.CharField(max_length=128)
          members = models.ManyToManyField(Person, through='Membership')
       
      class Membership(models.Model):
          person = models.ForeignKey(Person, on_delete=models.CASCADE)
          group = models.ForeignKey(Group, on_delete=models.CASCADE)
          date_joined = models.DateField()
          invite_reason = models.CharField(max_length=64)

      The first step in displaying this intermediate model in the admin is todefine an inline class for the Membership model:

      class MembershipInline(admin.TabularInline):
          model = Membership
          extra = 1

      This simple example uses the default InlineModelAdmin values for theMembership model, and limits the extra add forms to one. This could becustomized using any of the options available to InlineModelAdmin classes.

      Now create admin views for the Person and Group models:

      class PersonAdmin(admin.ModelAdmin):
          inlines = (MembershipInline,)
       
      class GroupAdmin(admin.ModelAdmin):
          inlines = (MembershipInline,)

      Finally, register your Person and Group models with the admin site:

      admin.site.register(Person, PersonAdmin)
      admin.site.register(Group, GroupAdmin)

      Now your admin site is set up to edit Membership objects inline fromeither the Person or the Group detail pages.

      Using generic relations as an inline

      It is possible to use an inline with generically related objects. Let's sayyou have the following models:

      from django.contrib.contenttypes.fields import GenericForeignKey
      from django.db import models
       
      class Image(models.Model):
          image = models.ImageField(upload_to="images")
          content_type = models.ForeignKey(ContentType, on_delete=models.CASCADE)
          object_id = models.PositiveIntegerField()
          content_object = GenericForeignKey("content_type", "object_id")
       
      class Product(models.Model):
          name = models.CharField(max_length=100)

      If you want to allow editing and creating an Image instance on theProduct, add/change views you can useGenericTabularInlineor GenericStackedInline (bothsubclasses of GenericInlineModelAdmin)provided by admin. They implement tabularand stacked visual layouts for the forms representing the inline objects,respectively, just like their non-generic counterparts. They behave just likeany other inline. In your admin.py for this example app:

      from django.contrib import admin
      from django.contrib.contenttypes.admin import GenericTabularInline
       
      from myproject.myapp.models import Image, Product
       
      class ImageInline(GenericTabularInline):
          model = Image
       
      class ProductAdmin(admin.ModelAdmin):
          inlines = [
              ImageInline,
          ]
       
      admin.site.register(Product, ProductAdmin)

      See the contenttypes documentation for morespecific information.

      Overriding admin templates

      It is relatively easy to override many of the templates which the admin moduleuses to generate the various pages of an admin site. You can even override afew of these templates for a specific app, or a specific model.

      Set up your projects admin template directories

      The admin template files are located in the contrib/admin/templates/admindirectory.

      In order to override one or more of them, first create an admin directoryin your project's templates directory. This can be any of the directoriesyou specified in the DIRS option of theDjangoTemplates backend in the TEMPLATES setting. If you havecustomized the 'loaders' option, be sure'django.template.loaders.filesystem.Loader' appears before'django.template.loaders.app_directories.Loader' so that your customtemplates will be found by the template loading system before those that areincluded with django.contrib.admin.

      Within this admin directory, create sub-directories named after your app.Within these app subdirectories create sub-directories named after your models.Note, that the admin app will lowercase the model name when looking for thedirectory, so make sure you name the directory in all lowercase if you aregoing to run your app on a case-sensitive filesystem.

      To override an admin template for a specific app, copy and edit the templatefrom the django/contrib/admin/templates/admin directory, and save it to oneof the directories you just created.

      For example, if we wanted to add a tool to the change list view for all themodels in an app named my_app, we would copycontrib/admin/templates/admin/change_list.html to thetemplates/admin/my_app/ directory of our project, and make any necessarychanges.

      If we wanted to add a tool to the change list view for only a specific modelnamed 'Page', we would copy that same file to thetemplates/admin/my_app/page directory of our project.

      Overriding vs. replacing an admin template

      Because of the modular design of the admin templates, it is usually neithernecessary nor advisable to replace an entire template. It is almost alwaysbetter to override only the section of the template which you need to change.

      To continue the example above, we want to add a new link next to theHistory tool for the Page model. After looking at change_form.htmlwe determine that we only need to override the object-tools-items block.Therefore here is our new change_form.html :

      {% extends "admin/change_form.html" %}
      {% load i18n admin_urls %}
      {% block object-tools-items %}
          <li>
              <a href="{% url opts|admin_urlname:'history' original.pk|admin_urlquote %}" class="historylink">{% trans "History" %}</a>
          </li>
          <li>
              <a href="mylink/" class="historylink">My Link</a>
          </li>
          {% if has_absolute_url %}
              <li>
                  <a href="{% url 'admin:view_on_site' content_type_id original.pk %}" class="viewsitelink">{% trans "View on site" %}</a>
              </li>
          {% endif %}
      {% endblock %}

      And that's it! If we placed this file in the templates/admin/my_appdirectory, our link would appear on the change form for all models withinmy_app.

      Templates which may be overridden per app or model

      Not every template in contrib/admin/templates/admin may be overridden perapp or per model. The following can:

      • app_index.html
      • change_form.html
      • change_list.html
      • delete_confirmation.html
      • object_history.html
      • popup_response.htmlChanged in Django 1.11:The ability to override the popup_response.html template was added.

      For those templates that cannot be overridden in this way, you may stilloverride them for your entire project. Just place the new version in yourtemplates/admin directory. This is particularly useful to create custom 404and 500 pages.

      Note

      Some of the admin templates, such as change_list_results.html are usedto render custom inclusion tags. These may be overridden, but in such casesyou are probably better off creating your own version of the tag inquestion and giving it a different name. That way you can use itselectively.

      Root and login templates

      If you wish to change the index, login or logout templates, you are better offcreating your own AdminSite instance (see below), and changing theAdminSite.index_template , AdminSite.login_template orAdminSite.logout_template properties.

      AdminSite objects

      • class AdminSite(name='admin')[source]
      • A Django administrative site is represented by an instance ofdjango.contrib.admin.sites.AdminSite; by default, an instance ofthis class is created as django.contrib.admin.site and you canregister your models and ModelAdmin instances with it.

      When constructing an instance of an AdminSite, you can providea unique instance name using the name argument to the constructor. Thisinstance name is used to identify the instance, especially whenreversing admin URLs. If no instance name isprovided, a default instance name of admin will be used.See Customizing the AdminSite class for an example of customizing theAdminSite class.

      AdminSite attributes

      Templates can override or extend base admin templates as described inOverriding admin templates.

      • AdminSite.site_header

      • The text to put at the top of each admin page, as an <h1> (a string).By default, this is "Django administration".

      • AdminSite.site_title

      • The text to put at the end of each admin page's <title> (a string). Bydefault, this is "Django site admin".

      • AdminSite.site_url

      • The URL for the "View site" link at the top of each admin page. By default,site_url is /. Set it to None to remove the link.

      For sites running on a subpath, the each_context() method checks ifthe current request has request.META['SCRIPT_NAME'] set and uses thatvalue if site_url isn't set to something other than /.

      • AdminSite.index_title

      • The text to put at the top of the admin index page (a string). By default,this is "Site administration".

      • AdminSite.index_template

      • Path to a custom template that will be used by the admin site main indexview.

      • AdminSite.app_index_template

      • Path to a custom template that will be used by the admin site app index view.

      • AdminSite.empty_value_display

      • The string to use for displaying empty values in the admin site's changelist. Defaults to a dash. The value can also be overridden on a perModelAdmin basis and on a custom field within a ModelAdmin bysetting an empty_value_display attribute on the field. SeeModelAdmin.empty_value_display for examples.

      • AdminSite.login_template

      • Path to a custom template that will be used by the admin site login view.

      • AdminSite.login_form

      • Subclass of AuthenticationForm thatwill be used by the admin site login view.

      • AdminSite.logout_template

      • Path to a custom template that will be used by the admin site logout view.

      • AdminSite.password_change_template

      • Path to a custom template that will be used by the admin site passwordchange view.

      • AdminSite.password_change_done_template

      • Path to a custom template that will be used by the admin site passwordchange done view.

      AdminSite methods

      • AdminSite.eachcontext(_request)[source]
      • Returns a dictionary of variables to put in the template context forevery page in the admin site.

      Includes the following variables and values by default:

      • site_header: AdminSite.site_header

      • site_title: AdminSite.site_title

      • site_url: AdminSite.site_url

      • has_permission: AdminSite.has_permission()

      • available_apps: a list of applications from the application registry available for the current user. Each entry in thelist is a dict representing an application with the following keys:

        • app_label: the application label
        • app_url: the URL of the application index in the admin
        • has_module_perms: a boolean indicating if displaying and accessing ofthe module's index page is permitted for the current user

        • models: a list of the models available in the applicationEach model is a dict with the following keys:

        • object_name: class name of the model

        • name: plural name of the model
        • perms: a dict tracking add, change, and delete permissions
        • admin_url: admin changelist URL for the model
        • add_url: admin URL to add a new model instance
        • AdminSite.haspermission(_request)[source]
        • Returns True if the user for the given HttpRequest has permissionto view at least one page in the admin site. Defaults to requiring bothUser.is_active andUser.is_staff to beTrue.
      • AdminSite.register(model_or_iterable, admin_class=None, **options)[source]
      • Registers the given model class (or iterable of classes) with the givenadmin_class. admin_class defaults toModelAdmin (the default admin options). Ifkeyword arguments are given — e.g. list_display — they'll be appliedas options to the admin class.

      Raises ImproperlyConfigured if a model isabstract. and django.contrib.admin.sites.AlreadyRegistered if a modelis already registered.

      Hooking AdminSite instances into your URLconf

      The last step in setting up the Django admin is to hook your AdminSiteinstance into your URLconf. Do this by pointing a given URL at theAdminSite.urls method. It is not necessary to useinclude().

      In this example, we register the default AdminSite instancedjango.contrib.admin.site at the URL /admin/

      # urls.py
      from django.contrib import admin
      from django.urls import path
       
      urlpatterns = [
          path('admin/', admin.site.urls),
      ]

      Customizing the AdminSite class

      If you'd like to set up your own admin site with custom behavior, you're freeto subclass AdminSite and override or add anything you like. Then, simplycreate an instance of your AdminSite subclass (the same way you'dinstantiate any other Python class) and register your models andModelAdmin subclasses with it instead of with the default site. Finally,update myproject/urls.py to reference your AdminSite subclass.

      myapp/admin.py

      from django.contrib.admin import AdminSite
       
      from .models import MyModel
       
      class MyAdminSite(AdminSite):
          site_header = 'Monty Python administration'
       
      admin_site = MyAdminSite(name='myadmin')
      admin_site.register(MyModel)

      myproject/urls.py

      from django.urls import path
       
      from myapp.admin import admin_site
       
      urlpatterns = [
          path('myadmin/', admin_site.urls),
      ]

      Note that you may not want autodiscovery of admin modules when using yourown AdminSite instance since you will likely be importing all the per-appadmin modules in your myproject.admin module. This means you need toput 'django.contrib.admin.apps.SimpleAdminConfig' instead of'django.contrib.admin' in your INSTALLED_APPS setting.

      Multiple admin sites in the same URLconf

      It's easy to create multiple instances of the admin site on the sameDjango-powered website. Just create multiple instances of AdminSite androot each one at a different URL.

      In this example, the URLs /basic-admin/ and /advanced-admin/ featureseparate versions of the admin site — using the AdminSite instancesmyproject.admin.basic_site and myproject.admin.advanced_site,respectively:

      # urls.py
      from django.urls import path
      from myproject.admin import advanced_site, basic_site
       
      urlpatterns = [
          path('basic-admin/', basic_site.urls),
          path('advanced-admin/', advanced_site.urls),
      ]

      AdminSite instances take a single argument to their constructor, theirname, which can be anything you like. This argument becomes the prefix to theURL names for the purposes of reversing them. Thisis only necessary if you are using more than one AdminSite.

      Adding views to admin sites

      Just like ModelAdmin, AdminSite provides aget_urls() methodthat can be overridden to define additional views for the site. To adda new view to your admin site, extend the baseget_urls() method to includea pattern for your new view.

      Note

      Any view you render that uses the admin templates, or extends the baseadmin template, should set request.current_app before rendering thetemplate. It should be set to either self.name if your view is on anAdminSite or self.admin_site.name if your view is on aModelAdmin.

      Adding a password reset feature

      You can add a password reset feature to the admin site by adding a few lines toyour URLconf. Specifically, add these four patterns:

      from django.contrib.auth import views as auth_views
       
      path(
          'admin/password_reset/',
          auth_views.PasswordResetView.as_view(),
          name='admin_password_reset',
      ),
      path(
          'admin/password_reset/done/',
          auth_views.PasswordResetDoneView.as_view(),
          name='password_reset_done',
      ),
      path(
          'reset/<uidb64>/<token>/',
          auth_views.PasswordResetConfirmView.as_view(),
          name='password_reset_confirm',
      ),
      path(
          'reset/done/',
          auth_views.PasswordResetCompleteView.as_view(),
          name='password_reset_complete',
      ),

      (This assumes you've added the admin at admin/ and requires that you putthe URLs starting with ^admin/ before the line that includes the admin appitself).

      The presence of the admin_password_reset named URL will cause a "forgottenyour password?" link to appear on the default admin log-in page under thepassword box.

      LogEntry objects

      • class models.LogEntry
      • The LogEntry class tracks additions, changes, and deletions of objectsdone through the admin interface.

      LogEntry attributes

      • LogEntry.action_time

      • The date and time of the action.

      • LogEntry.user

      • The user (an AUTH_USER_MODEL instance) who performed theaction.

      • LogEntry.content_type

      • The ContentType of themodified object.

      • LogEntry.object_id

      • The textual representation of the modified object's primary key.

      • LogEntry.object_repr

      • The object`s repr() after the modification.

      • LogEntry.action_flag

      • The type of action logged: ADDITION, CHANGE, DELETION.

      For example, to get a list of all additions done through the admin:

      from django.contrib.admin.models import ADDITION, LogEntry
       
      LogEntry.objects.filter(action_flag=ADDITION)

      • LogEntry.change_message
      • The detailed description of the modification. In the case of an edit, forexample, the message contains a list of the edited fields. The Django adminsite formats this content as a JSON structure, so thatget_change_message() can recompose a message translated in the currentuser language. Custom code might set this as a plain string though. You areadvised to use the get_change_message() method to retrieve this valueinstead of accessing it directly.

      LogEntry methods

      • LogEntry.get_edited_object()

      • A shortcut that returns the referenced object.

      • LogEntry.get_change_message()

      • Formats and translates change_message into the current userlanguage. Messages created before Django 1.10 will always be displayed inthe language in which they were logged.

      Reversing admin URLs

      When an AdminSite is deployed, the views provided by that site areaccessible using Django's URL reversing system.

      The AdminSite provides the following named URL patterns:

      Page	URL name	Parameters
      Index	index
      Login	login
      Logout	logout
      Password change	password_change
      Password change done	password_change_done
      i18n JavaScript	jsi18n
      Application index page	app_list	app_label
      Redirect to object's page	view_on_site	content_type_id, object_id

      Each ModelAdmin instance provides an additional set of named URLs:

      Page	URL name	Parameters
      Changelist	{{ applabel }}{{ modelname }}_changelist
      Add	{{ app_label }}{{ modelname }}_add
      History	{{ app_label }}{{ modelname }}_history	object_id
      Delete	{{ app_label }}{{ modelname }}_delete	object_id
      Change	{{ app_label }}{{ model_name }}_change	object_id

      The UserAdmin provides a named URL:

      Page	URL name	Parameters
      Password change	auth_user_password_change	user_id

      These named URLs are registered with the application namespace admin, andwith an instance namespace corresponding to the name of the Site instance.

      So - if you wanted to get a reference to the Change view for a particularChoice object (from the polls application) in the default admin, you wouldcall:

      >>> from django.urls import reverse
      >>> c = Choice.objects.get(...)
      >>> change_url = reverse('admin:polls_choice_change', args=(c.id,))

      This will find the first registered instance of the admin application(whatever the instance name), and resolve to the view for changingpoll.Choice instances in that instance.

      If you want to find a URL in a specific admin instance, provide the name ofthat instance as a current_app hint to the reverse call. For example,if you specifically wanted the admin view from the admin instance namedcustom, you would need to call:

      >>> change_url = reverse('admin:polls_choice_change', args=(c.id,), current_app='custom')

      For more details, see the documentation on reversing namespaced URLs.

      To allow easier reversing of the admin urls in templates, Django provides anadmin_urlname filter which takes an action as argument:

      {% load admin_urls %}
      <a href="{% url opts|admin_urlname:'add' %}">Add user</a>
      <a href="{% url opts|admin_urlname:'delete' user.pk %}">Delete this user</a>

      The action in the examples above match the last part of the URL names forModelAdmin instances described above. The opts variable can be anyobject which has an app_label and model_name attributes and is usuallysupplied by the admin views for the current model.

      The staff_member_required decorator

      • staffmember_required(_redirect_field_name='next', login_url='admin:login')[source]

      • This decorator is used on the admin views that require authorization. Aview decorated with this function will having the following behavior:

        • If the user is logged in, is a staff member (User.is_staff=True), andis active (User.is_active=True), execute the view normally.
        • Otherwise, the request will be redirected to the URL specified by thelogin_url parameter, with the originally requested path in a querystring variable specified by redirect_field_name. For example:/admin/login/?next=/admin/polls/question/3/.Example usage:

      from django.contrib.admin.views.decorators import staff_member_required
       
      @staff_member_required
      def my_view(request):
          ...