ModelAdmin objectsLink to this heading#
\n- \n
- \nclass ModelAdminLink to this definition# \n
The
\nModelAdminclass is the representation of a model in the admin\ninterface. Usually, these are stored in a file namedadmin.pyin your\napplication. Let’s take a look at an example of theModelAdmin:\n\nfrom django.contrib import admin\nfrom myapp.models import Author\n\nclass AuthorAdmin(admin.ModelAdmin):\n pass\nadmin.site.register(Author, AuthorAdmin)\n
The register decoratorLink to this heading#
\n- \n
- \nregister(*models, site=django.contrib.admin.sites.site)Link to this definition# \n
There is also a decorator for registering your
\nModelAdminclasses:\nfrom django.contrib import admin\nfrom .models import Author\n\n@admin.register(Author)\nclass AuthorAdmin(admin.ModelAdmin):\n pass\nIt’s given one or more model classes to register with the
\nModelAdmin.\nIf you’re using a customAdminSite, pass it using thesitekeyword\nargument:\nfrom django.contrib import admin\nfrom .models import Author, Editor, Reader\nfrom myproject.admin_site import custom_admin_site\n\n@admin.register(Author, Reader, Editor, site=custom_admin_site)\nclass PersonAdmin(admin.ModelAdmin):\n pass\nYou can’t use this decorator if you have to reference your model admin\nclass in its
\n__init__()method, e.g.\nsuper(PersonAdmin, self).__init__(*args, **kwargs). You can use\nsuper().__init__(*args, **kwargs).
Discovery of admin filesLink to this heading#
\nWhen you put 'django.contrib.admin' in your INSTALLED_APPS\nsetting, Django automatically looks for an admin module in each\napplication and imports it.
- \n
- \nclass apps.AdminConfigLink to this definition# \n
This is the default
\nAppConfigclass for the admin.\nIt callsautodiscover()when Django starts.
- \n
- \nclass apps.SimpleAdminConfigLink to this definition# \n
This class works like
\nAdminConfig,\nexcept it doesn’t callautodiscover().- \n
- \ndefault_siteLink to this definition# \n
A dotted import path to the default admin site’s class or to a callable\nthat returns a site instance. Defaults to\n
\n'django.contrib.admin.sites.AdminSite'. See\nOverriding the default admin site for usage.
- \n
- \nautodiscover()Link to this definition# \n
This function attempts to import an
\nadminmodule in each installed\napplication. Such modules are expected to register models with the admin.Typically you won’t need to call this function directly as\n
\nAdminConfigcalls it when Django starts.
If you are using a custom AdminSite, it is common to import all of the\nModelAdmin subclasses into your code and register them to the custom\nAdminSite. In that case, in order to disable auto-discovery, you should\nput 'django.contrib.admin.apps.SimpleAdminConfig' instead of\n'django.contrib.admin' in your INSTALLED_APPS setting.
ModelAdmin optionsLink to this heading#
\nThe ModelAdmin is very flexible. It has several options for dealing with\ncustomizing the interface. All options are defined on the ModelAdmin\nsubclass:
from django.contrib import admin\n\nclass AuthorAdmin(admin.ModelAdmin):\n date_hierarchy = 'pub_date'\n- \n
- \nModelAdmin.actionsLink to this definition# \n
A list of actions to make available on the change list page. See\nAdmin actions for details.
\n
- \n
- \nModelAdmin.actions_on_topLink to this definition# \n
- \n
- \nModelAdmin.actions_on_bottomLink to this definition# \n
Controls where on the page the actions bar appears. By default, the admin\nchangelist displays actions at the top of the page (
\nactions_on_top = True;\nactions_on_bottom = False).
- \n
- \nModelAdmin.actions_selection_counterLink to this definition# \n
Controls whether a selection counter is displayed next to the action dropdown.\nBy default, the admin changelist will display it\n(
\nactions_selection_counter = True).
- \n
- \nModelAdmin.date_hierarchyLink to this definition# \n
Set
\ndate_hierarchyto the name of aDateFieldorDateTimeField\nin your model, and the change list page will include a date-based drilldown\nnavigation by that field.Example:
\n\ndate_hierarchy = 'pub_date'\nYou can also specify a field on a related model using the
\n__lookup,\nfor example:\ndate_hierarchy = 'author__pub_date'\nThis will intelligently populate itself based on available data,\ne.g. if all the dates are in one month, it’ll show the day-level\ndrill-down only.
\n\n
- \n
- \nModelAdmin.empty_value_displayLink to this definition# \n
This attribute overrides the default display value for record’s fields that\nare empty (
\nNone, empty string, etc.). The default value is-(a\ndash). For example:\nfrom django.contrib import admin\n\nclass AuthorAdmin(admin.ModelAdmin):\n empty_value_display = '-empty-'\nYou can also override
\nempty_value_displayfor all admin pages with\nAdminSite.empty_value_display, or for specific fields like this:\n\nfrom django.contrib import admin\n\nclass AuthorAdmin(admin.ModelAdmin):\n fields = ('name', 'title', 'view_birth_date')\n\n @admin.display(empty_value='???')\n def view_birth_date(self, obj):\n return obj.birth_date\n
- \n
- \nModelAdmin.excludeLink to this definition# \n
This attribute, if given, should be a list of field names to exclude from\nthe form.
\nFor example, let’s consider the following model:
\n\nfrom django.db import models\n\nclass Author(models.Model):\n name = models.CharField(max_length=100)\n title = models.CharField(max_length=3)\n birth_date = models.DateField(blank=True, null=True)\nIf you want a form for the
\nAuthormodel that includes only thename\nandtitlefields, you would specifyfieldsorexcludelike\nthis:\nfrom django.contrib import admin\n\nclass AuthorAdmin(admin.ModelAdmin):\n fields = ('name', 'title')\n\nclass AuthorAdmin(admin.ModelAdmin):\n exclude = ('birth_date',)\nSince the Author model only has three fields,
\nname,title, and\nbirth_date, the forms resulting from the above declarations will\ncontain exactly the same fields.
- \n
- \nModelAdmin.fieldsLink to this definition# \n
Use the
\nfieldsoption to make simple layout changes in the forms on\nthe «add» and «change» pages such as showing only a subset of available\nfields, modifying their order, or grouping them into rows. For example, you\ncould define a simpler version of the admin form for the\ndjango.contrib.flatpages.models.FlatPagemodel as follows:\nclass FlatPageAdmin(admin.ModelAdmin):\n fields = ('url', 'title', 'content')\nIn the above example, only the fields
\nurl,titleandcontent\nwill be displayed, sequentially, in the form.fieldscan contain\nvalues defined inModelAdmin.readonly_fieldsto be displayed as\nread-only.For more complex layout needs, see the
\nfieldsetsoption.The
\nfieldsoption accepts the same types of values as\nlist_display, except that callables aren’t accepted.\nNames of model and model admin methods will only be used if they’re listed\ninreadonly_fields.To display multiple fields on the same line, wrap those fields in their own\ntuple. In this example, the
\nurlandtitlefields will display on the\nsame line and thecontentfield will be displayed below them on its\nown line:\n\nclass FlatPageAdmin(admin.ModelAdmin):\n fields = (('url', 'title'), 'content')\nIf neither
\nfieldsnorfieldsetsoptions are present,\nDjango will default to displaying each field that isn’t anAutoFieldand\nhaseditable=True, in a single fieldset, in the same order as the fields\nare defined in the model.
- \n
- \nModelAdmin.fieldsetsLink to this definition# \n
Set
\nfieldsetsto control the layout of admin «add» and «change» pages.
\nfieldsetsis a list of two-tuples, in which each two-tuple represents a\n<fieldset>on the admin form page. (A<fieldset>is a «section» of\nthe form.)The two-tuples are in the format
\n(name, field_options), wherename\nis a string representing the title of the fieldset andfield_optionsis\na dictionary of information about the fieldset, including a list of fields\nto be displayed in it.A full example, taken from the\n
\ndjango.contrib.flatpages.models.FlatPagemodel:\nfrom django.contrib import admin\n\nclass FlatPageAdmin(admin.ModelAdmin):\n fieldsets = (\n (None, {\n 'fields': ('url', 'title', 'content', 'sites')\n }),\n ('Advanced options', {\n 'classes': ('collapse',),\n 'fields': ('registration_required', 'template_name'),\n }),\n )\nThis results in an admin page that looks like:
\n![\"/el/3.2/_images/fieldsets.png\"](\"/el/3.2/_images/fieldsets.png\")
\nIf neither
\nfieldsetsnorfieldsoptions are present,\nDjango will default to displaying each field that isn’t anAutoFieldand\nhaseditable=True, in a single fieldset, in the same order as the fields\nare defined in the model.The
\nfield_optionsdictionary can have the following keys:- \n
- \n
fieldsA tuple of field names to display in this fieldset. This key is\nrequired.
\nExample:
\n\n{\n'fields': ('first_name', 'last_name', 'address', 'city', 'state'),\n}\nAs with the
\nfieldsoption, to display multiple\nfields on the same line, wrap those fields in their own tuple. In this\nexample, thefirst_nameandlast_namefields will display on\nthe same line:\n{\n'fields': (('first_name', 'last_name'), 'address', 'city', 'state'),\n}\n
\nfieldscan contain values defined in\nreadonly_fieldsto be displayed as read-only.If you add the name of a callable to
\nfields, the same rule applies\nas with thefieldsoption: the callable must be\nlisted inreadonly_fields. \n
\n- \n
classesA list or tuple containing extra CSS classes to apply to the fieldset.
\nExample:
\n\n{\n'classes': ('wide', 'extrapretty'),\n}\nTwo useful classes defined by the default admin site stylesheet are\n
\ncollapseandwide. Fieldsets with thecollapsestyle\nwill be initially collapsed in the admin and replaced with a small\n«click to expand» link. Fieldsets with thewidestyle will be\ngiven extra horizontal space. \n
\n- \n
descriptionA string of optional extra text to be displayed at the top of each\nfieldset, under the heading of the fieldset. This string is not\nrendered for
\nTabularInlinedue to its\nlayout.Note that this value is not HTML-escaped when it’s displayed in\nthe admin interface. This lets you include HTML if you so desire.\nAlternatively you can use plain text and\n
\ndjango.utils.html.escape()to escape any HTML special\ncharacters. \n
\n
- \n
- \nModelAdmin.filter_horizontalLink to this definition# \n
By default, a
\nManyToManyFieldis displayed in\nthe admin site with a<select multiple>. However, multiple-select boxes\ncan be difficult to use when selecting many items. Adding a\nManyToManyFieldto this list will instead use\na nifty unobtrusive JavaScript «filter» interface that allows searching\nwithin the options. The unselected and selected options appear in two boxes\nside by side. Seefilter_verticalto use a vertical\ninterface.
- \n
- \nModelAdmin.filter_verticalLink to this definition# \n
Same as
\nfilter_horizontal, but uses a vertical display\nof the filter interface with the box of unselected options appearing above\nthe box of selected options.
- \n
- \nModelAdmin.formLink to this definition# \n
By default a
\nModelFormis dynamically created for your model. It is\nused to create the form presented on both the add/change pages. You can\neasily provide your ownModelFormto override any default form behavior\non the add/change pages. Alternatively, you can customize the default\nform rather than specifying an entirely new one by using the\nModelAdmin.get_form()method.For an example see the section Adding custom validation to the admin.
\n\n\n
- \n
- \nModelAdmin.formfield_overridesLink to this definition# \n
This provides a quick-and-dirty way to override some of the\n
\nFieldoptions for use in the admin.\nformfield_overridesis a dictionary mapping a field class to a dict of\narguments to pass to the field at construction time.Since that’s a bit abstract, let’s look at a concrete example. The most\ncommon use of
\nformfield_overridesis to add a custom widget for a\ncertain type of field. So, imagine we’ve written aRichTextEditorWidget\nthat we’d like to use for large text fields instead of the default\n<textarea>. Here’s how we’d do that:\nfrom django.contrib import admin\nfrom django.db import models\n\n# Import our custom widget and our model from where they're defined\nfrom myapp.models import MyModel\nfrom myapp.widgets import RichTextEditorWidget\n\nclass MyModelAdmin(admin.ModelAdmin):\n formfield_overrides = {\n models.TextField: {'widget': RichTextEditorWidget},\n }\nNote that the key in the dictionary is the actual field class, not a\nstring. The value is another dictionary; these arguments will be passed to\nthe form field’s
\n\n__init__()method. See The Forms API for\ndetails.
- \n
- \nModelAdmin.inlinesLink to this definition# \n
See
\nInlineModelAdminobjects below as well as\nModelAdmin.get_formsets_with_inlines().
- \n
- \nModelAdmin.list_displayLink to this definition# \n
Set
\nlist_displayto control which fields are displayed on the change\nlist page of the admin.Example:
\n\nlist_display = ('first_name', 'last_name')\nIf you don’t set
\nlist_display, the admin site will display a single\ncolumn that displays the__str__()representation of each object.There are four types of values that can be used in
\nlist_display. All\nbut the simplest may use thedisplay()\ndecorator is used to customize how the field is presented:- \n
The name of a model field. For example:
\n\nclass PersonAdmin(admin.ModelAdmin):\n list_display = ('first_name', 'last_name')\n\nA callable that accepts one argument, the model instance. For example:
\n\n@admin.display(description='Name')\ndef upper_case_name(obj):\n return ("%s %s" % (obj.first_name, obj.last_name)).upper()\n\nclass PersonAdmin(admin.ModelAdmin):\n list_display = (upper_case_name,)\n\nA string representing a
\nModelAdminmethod that accepts one argument,\nthe model instance. For example:\nclass PersonAdmin(admin.ModelAdmin):\n list_display = ('upper_case_name',)\n\n @admin.display(description='Name')\n def upper_case_name(self, obj):\n return ("%s %s" % (obj.first_name, obj.last_name)).upper()\n\nA string representing a model attribute or method (without any required\narguments). For example:
\n\nfrom django.contrib import admin\nfrom django.db import models\n\nclass Person(models.Model):\n name = models.CharField(max_length=50)\n birthday = models.DateField()\n\n @admin.display(description='Birth decade')\n def decade_born_in(self):\n return '%d’s' % (self.birthday.year // 10 * 10)\n\nclass PersonAdmin(admin.ModelAdmin):\n list_display = ('name', 'decade_born_in')\n\n
A few special cases to note about
\nlist_display:- \n
If the field is a
ForeignKey, Django will display the\n__str__()of the related object. \nManyToManyFieldfields aren’t supported, because that would\nentail executing a separate SQL statement for each row in the table.\nIf you want to do this nonetheless, give your model a custom method,\nand add that method’s name tolist_display. (See below for more\non custom methods inlist_display.) \nIf the field is a
BooleanField, Django will display a pretty «yes»,\n«no», or «unknown» icon instead ofTrue,False, orNone. \nIf the string given is a method of the model,
\nModelAdminor a\ncallable, Django will HTML-escape the output by default. To escape\nuser input and allow your own unescaped tags, use\nformat_html().Here’s a full example model:
\n\nfrom django.contrib import admin\nfrom django.db import models\nfrom django.utils.html import format_html\n\nclass Person(models.Model):\n first_name = models.CharField(max_length=50)\n last_name = models.CharField(max_length=50)\n color_code = models.CharField(max_length=6)\n\n @admin.display\n def colored_name(self):\n return format_html(\n '<span style="color: #{};">{} {}</span>',\n self.color_code,\n self.first_name,\n self.last_name,\n )\n\nclass PersonAdmin(admin.ModelAdmin):\n list_display = ('first_name', 'last_name', 'colored_name')\n\nAs some examples have already demonstrated, when using a callable, a\nmodel method, or a
\n\nModelAdminmethod, you can customize the column’s\ntitle by wrapping the callable with the\ndisplay()decorator and passing the\ndescriptionargument. \nIf the value of a field is
\nNone, an empty string, or an iterable\nwithout elements, Django will display-(a dash). You can override\nthis withAdminSite.empty_value_display:\nfrom django.contrib import admin\n\nadmin.site.empty_value_display = '(None)'\nYou can also use
\nModelAdmin.empty_value_display:\nclass PersonAdmin(admin.ModelAdmin):\n empty_value_display = 'unknown'\nOr on a field level:
\n\n\nclass PersonAdmin(admin.ModelAdmin):\n list_display = ('name', 'birth_date_view')\n\n @admin.display(empty_value='unknown')\n def birth_date_view(self, obj):\n return obj.birth_date\n\nIf the string given is a method of the model,
\nModelAdminor a\ncallable that returnsTrue,False, orNone, Django will\ndisplay a pretty «yes», «no», or «unknown» icon if you wrap the method\nwith thedisplay()decorator passing the\nbooleanargument with the value set toTrue:\n\nfrom django.contrib import admin\nfrom django.db import models\n\nclass Person(models.Model):\n first_name = models.CharField(max_length=50)\n birthday = models.DateField()\n\n @admin.display(boolean=True)\n def born_in_fifties(self):\n return 1950 <= self.birthday.year < 1960\n\nclass PersonAdmin(admin.ModelAdmin):\n list_display = ('name', 'born_in_fifties')\n\nThe
\n__str__()method is just as valid inlist_displayas any\nother model method, so it’s perfectly OK to do this:\nlist_display = ('__str__', 'some_other_field')\n\nUsually, elements of
\nlist_displaythat aren’t actual database\nfields can’t be used in sorting (because Django does all the sorting\nat the database level).However, if an element of
\nlist_displayrepresents a certain database\nfield, you can indicate this fact by using the\ndisplay()decorator on the method, passing\ntheorderingargument:\nfrom django.contrib import admin\nfrom django.db import models\nfrom django.utils.html import format_html\n\nclass Person(models.Model):\n first_name = models.CharField(max_length=50)\n color_code = models.CharField(max_length=6)\n\n @admin.display(ordering='first_name')\n def colored_first_name(self):\n return format_html(\n '<span style="color: #{};">{}</span>',\n self.color_code,\n self.first_name,\n )\n\nclass PersonAdmin(admin.ModelAdmin):\n list_display = ('first_name', 'colored_first_name')\nThe above will tell Django to order by the
\nfirst_namefield when\ntrying to sort bycolored_first_namein the admin.To indicate descending order with the
\norderingargument you can use a\nhyphen prefix on the field name. Using the above example, this would look\nlike:\n@admin.display(ordering='-first_name')\nThe
\norderingargument supports query lookups to sort by values on\nrelated models. This example includes an «author first name» column in\nthe list display and allows sorting it by first name:\nclass Blog(models.Model):\n title = models.CharField(max_length=255)\n author = models.ForeignKey(Person, on_delete=models.CASCADE)\n\nclass BlogAdmin(admin.ModelAdmin):\n list_display = ('title', 'author', 'author_first_name')\n\n @admin.display(ordering='author__first_name')\n def author_first_name(self, obj):\n return obj.author.first_name\nQuery expressions may be used with the\n
\norderingargument:\n\nfrom django.db.models import Value\nfrom django.db.models.functions import Concat\n\nclass Person(models.Model):\n first_name = models.CharField(max_length=50)\n last_name = models.CharField(max_length=50)\n\n @admin.display(ordering=Concat('first_name', Value(' '), 'last_name'))\n def full_name(self):\n return self.first_name + ' ' + self.last_name\n\nElements of
\nlist_displaycan also be properties:\nclass Person(models.Model):\n first_name = models.CharField(max_length=50)\n last_name = models.CharField(max_length=50)\n\n @property\n @admin.display(\n ordering='last_name',\n description='Full name of the person',\n )\n def full_name(self):\n return self.first_name + ' ' + self.last_name\n\nclass PersonAdmin(admin.ModelAdmin):\n list_display = ('full_name',)\nNote that
\n@propertymust be above@display. If you’re using the\nold way – setting the display-related attributes directly rather than\nusing thedisplay()decorator – be aware\nthat theproperty()function and not the@propertydecorator\nmust be used:\ndef my_property(self):\n return self.first_name + ' ' + self.last_name\nmy_property.short_description = "Full name of the person"\nmy_property.admin_order_field = 'last_name'\n\nfull_name = property(my_property)\n\nThe field names in
list_displaywill also appear as CSS classes in\nthe HTML output, in the form ofcolumn-<field_name>on each<th>\nelement. This can be used to set column widths in a CSS file for example. \nDjango will try to interpret every element of
\nlist_displayin this\norder:- \n
A field of the model.
\nA callable.
\nA string representing a
ModelAdminattribute. \nA string representing a model attribute.
\n
For example if you have
\nfirst_nameas a model field and\nas aModelAdminattribute, the model field will be used. \n
- \n
- \nModelAdmin.list_display_linksLink to this definition# \n
Use
\nlist_display_linksto control if and which fields in\nlist_displayshould be linked to the «change» page for an object.By default, the change list page will link the first column – the first\nfield specified in
\nlist_display– to the change page for each item.\nButlist_display_linkslets you change this:- \n
Set it to
Noneto get no links at all. \nSet it to a list or tuple of fields (in the same format as\n
\nlist_display) whose columns you want converted to links.You can specify one or many fields. As long as the fields appear in\n
\nlist_display, Django doesn’t care how many (or how few) fields are\nlinked. The only requirement is that if you want to use\nlist_display_linksin this fashion, you must definelist_display. \n
In this example, the
\nfirst_nameandlast_namefields will be\nlinked on the change list page:\nclass PersonAdmin(admin.ModelAdmin):\n list_display = ('first_name', 'last_name', 'birthday')\n list_display_links = ('first_name', 'last_name')\nIn this example, the change list page grid will have no links:
\n\nclass AuditEntryAdmin(admin.ModelAdmin):\n list_display = ('timestamp', 'message')\n list_display_links = None\n
- \n
- \nModelAdmin.list_editableLink to this definition# \n
Set
\n\nlist_editableto a list of field names on the model which will\nallow editing on the change list page. That is, fields listed in\nlist_editablewill be displayed as form widgets on the change list\npage, allowing users to edit and save multiple rows at once.
- \n
- \nModelAdmin.list_filterLink to this definition# \n
Set
\nlist_filterto activate filters in the right sidebar of the change\nlist page of the admin, as illustrated in the following screenshot:![\"/el/3.2/_images/list_filter.png\"](\"/el/3.2/_images/list_filter.png\")
\n
\nlist_filtershould be a list or tuple of elements, where each element\nshould be of one of the following types:- \n
a field name, where the specified field should be either a\n
\nBooleanField,CharField,DateField,DateTimeField,\nIntegerField,ForeignKeyorManyToManyField, for example:\nclass PersonAdmin(admin.ModelAdmin):\n list_filter = ('is_staff', 'company')\nField names in
\nlist_filtercan also span relations\nusing the__lookup, for example:\nclass PersonAdmin(admin.UserAdmin):\n list_filter = ('company__name',)\n\na class inheriting from
\ndjango.contrib.admin.SimpleListFilter,\nwhich you need to provide thetitleandparameter_name\nattributes to and override thelookupsandquerysetmethods,\ne.g.:\n\nfrom datetime import date\n\nfrom django.contrib import admin\nfrom django.utils.translation import gettext_lazy as _\n\nclass DecadeBornListFilter(admin.SimpleListFilter):\n # Human-readable title which will be displayed in the\n # right admin sidebar just above the filter options.\n title = _('decade born')\n\n # Parameter for the filter that will be used in the URL query.\n parameter_name = 'decade'\n\n def lookups(self, request, model_admin):\n """\n Returns a list of tuples. The first element in each\n tuple is the coded value for the option that will\n appear in the URL query. The second element is the\n human-readable name for the option that will appear\n in the right sidebar.\n """\n return (\n ('80s', _('in the eighties')),\n ('90s', _('in the nineties')),\n )\n\n def queryset(self, request, queryset):\n """\n Returns the filtered queryset based on the value\n provided in the query string and retrievable via\n `self.value()`.\n """\n # Compare the requested value (either '80s' or '90s')\n # to decide how to filter the queryset.\n if self.value() == '80s':\n return queryset.filter(birthday__gte=date(1980, 1, 1),\n birthday__lte=date(1989, 12, 31))\n if self.value() == '90s':\n return queryset.filter(birthday__gte=date(1990, 1, 1),\n birthday__lte=date(1999, 12, 31))\n\nclass PersonAdmin(admin.ModelAdmin):\n list_filter = (DecadeBornListFilter,)\n\na tuple, where the first element is a field name and the second\nelement is a class inheriting from\n
\ndjango.contrib.admin.FieldListFilter, for example:\nclass PersonAdmin(admin.ModelAdmin):\n list_filter = (\n ('is_staff', admin.BooleanFieldListFilter),\n )\nYou can limit the choices of a related model to the objects involved in\nthat relation using
\nRelatedOnlyFieldListFilter:\nclass BookAdmin(admin.ModelAdmin):\n list_filter = (\n ('author', admin.RelatedOnlyFieldListFilter),\n )\nAssuming
\nauthoris aForeignKeyto aUsermodel, this will\nlimit thelist_filterchoices to the users who have written a book\ninstead of listing all users.You can filter empty values using
\nEmptyFieldListFilter, which can\nfilter on both empty strings and nulls, depending on what the field\nallows to store:\n\n\n\nclass BookAdmin(admin.ModelAdmin):\n list_filter = (\n ('title', admin.EmptyFieldListFilter),\n )\n\n
List filter’s typically appear only if the filter has more than one choice.\nA filter’s
\nhas_output()method controls whether or not it appears.It is possible to specify a custom template for rendering a list filter:
\n\nclass FilterWithCustomTemplate(admin.SimpleListFilter):\n template = "custom_template.html"\nSee the default template provided by Django (
\nadmin/filter.html) for\na concrete example.
- \n
- \nModelAdmin.list_max_show_allLink to this definition# \n
Set
\nlist_max_show_allto control how many items can appear on a «Show\nall» admin change list page. The admin will display a «Show all» link on the\nchange list only if the total result count is less than or equal to this\nsetting. By default, this is set to200.
- \n
- \nModelAdmin.list_per_pageLink to this definition# \n
Set
\nlist_per_pageto control how many items appear on each paginated\nadmin change list page. By default, this is set to100.
- \n\n
Set
\nlist_select_relatedto tell Django to use\nselect_related()in retrieving\nthe list of objects on the admin change list page. This can save you a\nbunch of database queries.The value should be either a boolean, a list or a tuple. Default is\n
\nFalse.When value is
\nTrue,select_related()will always be called. When\nvalue is set toFalse, Django will look atlist_displayand call\nselect_related()if anyForeignKeyis present.If you need more fine-grained control, use a tuple (or list) as value for\n
\nlist_select_related. Empty tuple will prevent Django from calling\nselect_relatedat all. Any other tuple will be passed directly to\nselect_relatedas parameters. For example:\nclass ArticleAdmin(admin.ModelAdmin):\n list_select_related = ('author', 'category')\nwill call
\nselect_related('author', 'category').If you need to specify a dynamic value based on the request, you can\nimplement a
\n\nget_list_select_related()method.
- \n
- \nModelAdmin.orderingLink to this definition# \n
Set
\norderingto specify how lists of objects should be ordered in the\nDjango admin views. This should be a list or tuple in the same format as a\nmodel’sorderingparameter.If this isn’t provided, the Django admin will use the model’s default\nordering.
\nIf you need to specify a dynamic order (for example depending on user or\nlanguage) you can implement a
\n\nget_ordering()method.
- \n
- \nModelAdmin.paginatorLink to this definition# \n
The paginator class to be used for pagination. By default,\n
\ndjango.core.paginator.Paginatoris used. If the custom paginator\nclass doesn’t have the same constructor interface as\ndjango.core.paginator.Paginator, you will also need to\nprovide an implementation forModelAdmin.get_paginator().
- \n
- \nModelAdmin.prepopulated_fieldsLink to this definition# \n
Set
\nprepopulated_fieldsto a dictionary mapping field names to the\nfields it should prepopulate from:\nclass ArticleAdmin(admin.ModelAdmin):\n prepopulated_fields = {"slug": ("title",)}\nWhen set, the given fields will use a bit of JavaScript to populate from\nthe fields assigned. The main use for this functionality is to\nautomatically generate the value for
\nSlugFieldfields from one or more\nother fields. The generated value is produced by concatenating the values\nof the source fields, and then by transforming that result into a valid\nslug (e.g. substituting dashes for spaces and lowercasing ASCII letters).Prepopulated fields aren’t modified by JavaScript after a value has been\nsaved. It’s usually undesired that slugs change (which would cause an\nobject’s URL to change if the slug is used in it).
\n
\n\nprepopulated_fieldsdoesn’t acceptDateTimeField,ForeignKey,\nOneToOneField, andManyToManyFieldfields.
- \n
- \nModelAdmin.preserve_filtersLink to this definition# \n
By default, applied filters are preserved on the list view after creating,\nediting, or deleting an object. You can have filters cleared by setting\nthis attribute to
\nFalse.
- \n
- \nModelAdmin.radio_fieldsLink to this definition# \n
By default, Django’s admin uses a select-box interface (<select>) for\nfields that are
\nForeignKeyor havechoicesset. If a field is\npresent inradio_fields, Django will use a radio-button interface\ninstead. Assuminggroupis aForeignKeyon thePersonmodel:\nclass PersonAdmin(admin.ModelAdmin):\n radio_fields = {"group": admin.VERTICAL}\nYou have the choice of using
\nHORIZONTALorVERTICALfrom the\ndjango.contrib.adminmodule.Don’t include a field in
\nradio_fieldsunless it’s aForeignKeyor has\nchoicesset.
- \n
- \nModelAdmin.autocomplete_fieldsLink to this definition# \n
\nautocomplete_fieldsis a list ofForeignKeyand/or\nManyToManyFieldfields you would like to change to Select2 autocomplete inputs.By default, the admin uses a select-box interface (
\n<select>) for\nthose fields. Sometimes you don’t want to incur the overhead of selecting\nall the related instances to display in the dropdown.The Select2 input looks similar to the default input but comes with a\nsearch feature that loads the options asynchronously. This is faster and\nmore user-friendly if the related model has many instances.
\nYou must define
\nsearch_fieldson the related object’s\nModelAdminbecause the autocomplete search uses it.To avoid unauthorized data disclosure, users must have the
\nviewor\nchangepermission to the related object in order to use autocomplete.Ordering and pagination of the results are controlled by the related\n
\nModelAdmin’sget_ordering()and\nget_paginator()methods.In the following example,
\nChoiceAdminhas an autocomplete field for the\nForeignKeyto theQuestion. The results are filtered by the\nquestion_textfield and ordered by thedate_createdfield:\n\nclass QuestionAdmin(admin.ModelAdmin):\n ordering = ['date_created']\n search_fields = ['question_text']\n\nclass ChoiceAdmin(admin.ModelAdmin):\n autocomplete_fields = ['question']\n
- \n
- \nModelAdmin.raw_id_fieldsLink to this definition# \n
By default, Django’s admin uses a select-box interface (<select>) for\nfields that are
\nForeignKey. Sometimes you don’t want to incur the\noverhead of having to select all the related instances to display in the\ndrop-down.
\nraw_id_fieldsis a list of fields you would like to change\ninto anInputwidget for either aForeignKeyor\nManyToManyField:\nclass ArticleAdmin(admin.ModelAdmin):\n raw_id_fields = ("newspaper",)\nThe
\nraw_id_fieldsInputwidget should contain a primary key if the\nfield is aForeignKeyor a comma separated list of values if the field\nis aManyToManyField. Theraw_id_fieldswidget shows a magnifying\nglass button next to the field which allows users to search for and select\na value:![\"/el/3.2/_images/raw_id_fields.png\"](\"/el/3.2/_images/raw_id_fields.png\")
\n
- \n
- \nModelAdmin.readonly_fieldsLink to this definition# \n
By default the admin shows all fields as editable. Any fields in this\noption (which should be a
\nlistortuple) will display its data\nas-is and non-editable; they are also excluded from the\nModelFormused for creating and editing. Note that\nwhen specifyingModelAdmin.fieldsorModelAdmin.fieldsets\nthe read-only fields must be present to be shown (they are ignored\notherwise).If
\nreadonly_fieldsis used without defining explicit ordering through\nModelAdmin.fieldsorModelAdmin.fieldsetsthey will be\nadded last after all editable fields.A read-only field can not only display data from a model’s field, it can\nalso display the output of a model’s method or a method of the\n
\nModelAdminclass itself. This is very similar to the way\nModelAdmin.list_displaybehaves. This provides a way to use the\nadmin interface to provide feedback on the status of the objects being\nedited, for example:\nfrom django.contrib import admin\nfrom django.utils.html import format_html_join\nfrom django.utils.safestring import mark_safe\n\nclass PersonAdmin(admin.ModelAdmin):\n readonly_fields = ('address_report',)\n\n # description functions like a model field's verbose_name\n @admin.display(description='Address')\n def address_report(self, instance):\n # assuming get_full_address() returns a list of strings\n # for each line of the address and you want to separate each\n # line by a linebreak\n return format_html_join(\n mark_safe('<br>'),\n '{}',\n ((line,) for line in instance.get_full_address()),\n ) or mark_safe("<span class='errors'>I can't determine this address.</span>")\n
- \n
- \nModelAdmin.save_asLink to this definition# \n
Set
\nsave_asto enable a «save as new» feature on admin change forms.Normally, objects have three save options: «Save», «Save and continue\nediting», and «Save and add another». If
\nsave_asisTrue, «Save\nand add another» will be replaced by a «Save as new» button that creates a\nnew object (with a new ID) rather than updating the existing object.By default,
\nsave_asis set toFalse.
- \n
- \nModelAdmin.save_as_continueLink to this definition# \n
When
\nsave_as=True, the default redirect after saving the\nnew object is to the change view for that object. If you set\nsave_as_continue=False, the redirect will be to the changelist view.By default,
\nsave_as_continueis set toTrue.
- \n
- \nModelAdmin.save_on_topLink to this definition# \n
Set
\nsave_on_topto add save buttons across the top of your admin change\nforms.Normally, the save buttons appear only at the bottom of the forms. If you\nset
\nsave_on_top, the buttons will appear both on the top and the\nbottom.By default,
\nsave_on_topis set toFalse.
- \n
- \nModelAdmin.search_fieldsLink to this definition# \n
Set
\nsearch_fieldsto enable a search box on the admin change list page.\nThis should be set to a list of field names that will be searched whenever\nsomebody submits a search query in that text box.These fields should be some kind of text field, such as
\nCharFieldor\nTextField. You can also perform a related lookup on aForeignKeyor\nManyToManyFieldwith the lookup API «follow» notation:\nsearch_fields = ['foreign_key__related_fieldname']\nFor example, if you have a blog entry with an author, the following\ndefinition would enable searching blog entries by the email address of the\nauthor:
\n\nsearch_fields = ['user__email']\nWhen somebody does a search in the admin search box, Django splits the\nsearch query into words and returns all objects that contain each of the\nwords, case-insensitive (using the
\nicontainslookup), where each\nword must be in at least one ofsearch_fields. For example, if\nsearch_fieldsis set to['first_name', 'last_name']and a user\nsearches forjohn lennon, Django will do the equivalent of this SQL\nWHEREclause:\nWHERE (first_name ILIKE '%john%' OR last_name ILIKE '%john%')\nAND (first_name ILIKE '%lennon%' OR last_name ILIKE '%lennon%')\nThe search query can contain quoted phrases with spaces. For example, if a\nuser searches for
\n"john winston"or'john winston', Django will do\nthe equivalent of this SQLWHEREclause:\nWHERE (first_name ILIKE '%john winston%' OR last_name ILIKE '%john winston%')\nIf you don’t want to use
\nicontainsas the lookup, you can use any\nlookup by appending it the field. For example, you could useexact\nby settingsearch_fieldsto['first_name__exact'].Some (older) shortcuts for specifying a field lookup are also available.\nYou can prefix a field in
\nsearch_fieldswith the following characters\nand it’s equivalent to adding__<lookup>to the field:\n\n\n
\nPrefix
Lookup
^
\n =
\n @
\n None
\n If you need to customize search you can use\n
\n\nModelAdmin.get_search_results()to provide additional or alternate\nsearch behavior.
- \n
- \nModelAdmin.show_full_result_countLink to this definition# \n
Set
\nshow_full_result_countto control whether the full count of objects\nshould be displayed on a filtered admin page (e.g.99 results (103 total)).\nIf this option is set toFalse, a text like99 results (Show all)\nis displayed instead.The default of
\nshow_full_result_count=Truegenerates a query to perform\na full count on the table which can be expensive if the table contains a\nlarge number of rows.
- \n
- \nModelAdmin.sortable_byLink to this definition# \n
By default, the change list page allows sorting by all model fields (and\ncallables that use the
\norderingargument to the\ndisplay()decorator or have the\nadmin_order_fieldattribute) specified inlist_display.If you want to disable sorting for some columns, set
\nsortable_byto\na collection (e.g.list,tuple, orset) of the subset of\nlist_displaythat you want to be sortable. An empty collection\ndisables sorting for all columns.If you need to specify this list dynamically, implement a\n
\nget_sortable_by()method instead.
- \n
- \nModelAdmin.view_on_siteLink to this definition# \n
Set
\nview_on_siteto control whether or not to display the «View on site» link.\nThis 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
\nTrue(the\ndefault), the object’sget_absolute_url()\nmethod will be used to generate the url.If your model has a
\nget_absolute_url()method\nbut you don’t want the «View on site» button to appear, you only need to set\nview_on_sitetoFalse:\nfrom django.contrib import admin\n\nclass PersonAdmin(admin.ModelAdmin):\n view_on_site = False\nIn case it is a callable, it accepts the model instance as a parameter.\nFor example:
\n\nfrom django.contrib import admin\nfrom django.urls import reverse\n\nclass PersonAdmin(admin.ModelAdmin):\n def view_on_site(self, obj):\n url = reverse('person-detail', kwargs={'slug': obj.slug})\n return 'https://example.com' + url\n
Custom template optionsLink to this heading#
\nThe Overriding admin templates section describes how to override or extend\nthe default admin templates. Use the following options to override the default\ntemplates used by the ModelAdmin views:
- \n
- \nModelAdmin.add_form_templateLink to this definition# \n
Path to a custom template, used by
\nadd_view().
- \n
- \nModelAdmin.change_form_templateLink to this definition# \n
Path to a custom template, used by
\nchange_view().
- \n
- \nModelAdmin.change_list_templateLink to this definition# \n
Path to a custom template, used by
\nchangelist_view().
- \n
- \nModelAdmin.delete_confirmation_templateLink to this definition# \n
Path to a custom template, used by
\ndelete_view()for displaying a\nconfirmation page when deleting one or more objects.
- \n
- \nModelAdmin.delete_selected_confirmation_templateLink to this definition# \n
Path to a custom template, used by the
\ndelete_selectedaction method\nfor displaying a confirmation page when deleting one or more objects. See\nthe actions documentation.
- \n
- \nModelAdmin.object_history_templateLink to this definition# \n
Path to a custom template, used by
\nhistory_view().
- \n
- \nModelAdmin.popup_response_templateLink to this definition# \n
Path to a custom template, used by
\nresponse_add(),\nresponse_change(), andresponse_delete().
ModelAdmin methodsLink to this heading#
\n\n- \n
- \nModelAdmin.save_model(request, obj, form, change)Link to this definition# \n
The
\nsave_modelmethod is given theHttpRequest, a model instance,\naModelForminstance, and a boolean value based on whether it is adding\nor changing the object. Overriding this method allows doing pre- or\npost-save operations. Callsuper().save_model()to save the object\nusingModel.save().For example to attach
\nrequest.userto the object prior to saving:\nfrom django.contrib import admin\n\nclass ArticleAdmin(admin.ModelAdmin):\n def save_model(self, request, obj, form, change):\n obj.user = request.user\n super().save_model(request, obj, form, change)\n
- \n
- \nModelAdmin.delete_model(request, obj)Link to this definition# \n
The
\ndelete_modelmethod is given theHttpRequestand a model\ninstance. Overriding this method allows doing pre- or post-delete\noperations. Callsuper().delete_model()to delete the object using\nModel.delete().
- \n
- \nModelAdmin.delete_queryset(request, queryset)Link to this definition# \n
The
\ndelete_queryset()method is given theHttpRequestand a\nQuerySetof objects to be deleted. Override this method to customize\nthe deletion process for the «delete selected objects» action.
- \n
- \nModelAdmin.save_formset(request, form, formset, change)Link to this definition# \n
The
\nsave_formsetmethod is given theHttpRequest, the parent\nModelForminstance and a boolean value based on whether it is adding or\nchanging the parent object.For example, to attach
\nrequest.userto each changed formset\nmodel instance:\nclass ArticleAdmin(admin.ModelAdmin):\n def save_formset(self, request, form, formset, change):\n instances = formset.save(commit=False)\n for obj in formset.deleted_objects:\n obj.delete()\n for instance in instances:\n instance.user = request.user\n instance.save()\n formset.save_m2m()\nSee also Saving objects in the formset.
\n
- \n
- \nModelAdmin.get_ordering(request)Link to this definition# \n
The
\nget_orderingmethod takes arequestas parameter and\nis expected to return alistortuplefor ordering similar\nto theorderingattribute. For example:\nclass PersonAdmin(admin.ModelAdmin):\n\n def get_ordering(self, request):\n if request.user.is_superuser:\n return ['name', 'rank']\n else:\n return ['name']\n
- \n
- \nModelAdmin.get_search_results(request, queryset, search_term)Link to this definition# \n
The
\nget_search_resultsmethod modifies the list of objects displayed\ninto those that match the provided search term. It accepts the request, a\nqueryset that applies the current filters, and the user-provided search term.\nIt returns a tuple containing a queryset modified to implement the search, and\na boolean indicating if the results may contain duplicates.The default implementation searches the fields named in
\nModelAdmin.search_fields.This method may be overridden with your own custom search method. For\nexample, you might wish to search by an integer field, or use an external\ntool such as Solr or Haystack. You must establish if the queryset changes\nimplemented by your search method may introduce duplicates into the results,\nand return
\nTruein the second element of the return value.For example, to search by
\nnameandage, you could use:\nclass PersonAdmin(admin.ModelAdmin):\n list_display = ('name', 'age')\n search_fields = ('name',)\n\n def get_search_results(self, request, queryset, search_term):\n queryset, may_have_duplicates = super().get_search_results(\n request, queryset, search_term,\n )\n try:\n search_term_as_int = int(search_term)\n except ValueError:\n pass\n else:\n queryset |= self.model.objects.filter(age=search_term_as_int)\n return queryset, may_have_duplicates\nThis implementation is more efficient than
\nsearch_fields =\n('name', '=age')which results in a string comparison for the numeric\nfield, for example... OR UPPER("polls_choice"."votes"::text) = UPPER('4')\non PostgreSQL.
- \n\n
The
\nsave_relatedmethod is given theHttpRequest, the parent\nModelForminstance, the list of inline formsets and a boolean value\nbased on whether the parent is being added or changed. Here you can do any\npre- or post-save operations for objects related to the parent. Note\nthat at this point the parent object and its form have already been saved.
- \n
- \nModelAdmin.get_autocomplete_fields(request)Link to this definition# \n
The
\nget_autocomplete_fields()method is given theHttpRequestand is\nexpected to return alistortupleof field names that will be\ndisplayed with an autocomplete widget as described above in the\nModelAdmin.autocomplete_fieldssection.
- \n
- \nModelAdmin.get_readonly_fields(request, obj=None)Link to this definition# \n
The
\nget_readonly_fieldsmethod is given theHttpRequestand the\nobjbeing edited (orNoneon an add form) and is expected to return\nalistortupleof field names that will be displayed as read-only,\nas described above in theModelAdmin.readonly_fieldssection.
- \n
- \nModelAdmin.get_prepopulated_fields(request, obj=None)Link to this definition# \n
The
\nget_prepopulated_fieldsmethod is given theHttpRequestand the\nobjbeing edited (orNoneon an add form) and is expected to return\nadictionary, as described above in theModelAdmin.prepopulated_fields\nsection.
- \n
- \nModelAdmin.get_list_display(request)Link to this definition# \n
The
\nget_list_displaymethod is given theHttpRequestand is\nexpected to return alistortupleof field names that will be\ndisplayed on the changelist view as described above in the\nModelAdmin.list_displaysection.
- \n
- \nModelAdmin.get_list_display_links(request, list_display)Link to this definition# \n
The
\nget_list_display_linksmethod is given theHttpRequestand\nthelistortuplereturned byModelAdmin.get_list_display().\nIt is expected to return eitherNoneor alistortupleof field\nnames on the changelist that will be linked to the change view, as described\nin theModelAdmin.list_display_linkssection.
- \n
- \nModelAdmin.get_exclude(request, obj=None)Link to this definition# \n
The
\nget_excludemethod is given theHttpRequestand theobj\nbeing edited (orNoneon an add form) and is expected to return a list\nof fields, as described inModelAdmin.exclude.
- \n
- \nModelAdmin.get_fields(request, obj=None)Link to this definition# \n
The
\nget_fieldsmethod is given theHttpRequestand theobj\nbeing edited (orNoneon an add form) and is expected to return a list\nof fields, as described above in theModelAdmin.fieldssection.
- \n
- \nModelAdmin.get_fieldsets(request, obj=None)Link to this definition# \n
The
\nget_fieldsetsmethod is given theHttpRequestand theobj\nbeing edited (orNoneon an add form) and is expected to return a list\nof two-tuples, in which each two-tuple represents a<fieldset>on the\nadmin form page, as described above in theModelAdmin.fieldsetssection.
- \n
- \nModelAdmin.get_list_filter(request)Link to this definition# \n
The
\nget_list_filtermethod is given theHttpRequestand is expected\nto return the same kind of sequence type as for the\nlist_filterattribute.
- \n\n
The
\nget_list_select_relatedmethod is given theHttpRequestand\nshould return a boolean or list asModelAdmin.list_select_related\ndoes.
- \n
- \nModelAdmin.get_search_fields(request)Link to this definition# \n
The
\nget_search_fieldsmethod is given theHttpRequestand is expected\nto return the same kind of sequence type as for the\nsearch_fieldsattribute.
- \n
- \nModelAdmin.get_sortable_by(request)Link to this definition# \n
The
\nget_sortable_by()method is passed theHttpRequestand is\nexpected to return a collection (e.g.list,tuple, orset) of\nfield names that will be sortable in the change list page.Its default implementation returns
\nsortable_byif it’s set,\notherwise it defers toget_list_display().For example, to prevent one or more columns from being sortable:
\n\nclass PersonAdmin(admin.ModelAdmin):\n\n def get_sortable_by(self, request):\n return {*self.get_list_display(request)} - {'rank'}\n
- \n
- \nModelAdmin.get_inline_instances(request, obj=None)Link to this definition# \n
The
\nget_inline_instancesmethod is given theHttpRequestand the\nobjbeing edited (orNoneon an add form) and is expected to return\nalistortupleofInlineModelAdmin\nobjects, as described below in theInlineModelAdmin\nsection. For example, the following would return inlines without the default\nfiltering based on add, change, delete, and view permissions:\nclass MyModelAdmin(admin.ModelAdmin):\n inlines = (MyInline,)\n\n def get_inline_instances(self, request, obj=None):\n return [inline(self.model, self.admin_site) for inline in self.inlines]\nIf you override this method, make sure that the returned inlines are\ninstances of the classes defined in
\ninlinesor you might encounter\na «Bad Request» error when adding related objects.
- \n
- \nModelAdmin.get_inlines(request, obj)Link to this definition# \n
The
\nget_inlinesmethod is given theHttpRequestand the\nobjbeing edited (orNoneon an add form) and is expected to return\nan iterable of inlines. You can override this method to dynamically add\ninlines based on the request or model instance instead of specifying them\ninModelAdmin.inlines.
- \n
- \nModelAdmin.get_urls()Link to this definition# \n
The
\nget_urlsmethod on aModelAdminreturns the URLs to be used for\nthat ModelAdmin in the same way as a URLconf. Therefore you can extend\nthem as documented in URL dispatcher:\nfrom django.contrib import admin\nfrom django.template.response import TemplateResponse\nfrom django.urls import path\n\nclass MyModelAdmin(admin.ModelAdmin):\n def get_urls(self):\n urls = super().get_urls()\n my_urls = [\n path('my_view/', self.my_view),\n ]\n return my_urls + urls\n\n def my_view(self, request):\n # ...\n context = dict(\n # Include common variables for rendering the admin template.\n self.admin_site.each_context(request),\n # Anything else you want in the context...\n key=value,\n )\n return TemplateResponse(request, "sometemplate.html", context)\nIf you want to use the admin layout, extend from
\nadmin/base_site.html:\n\n{% extends "admin/base_site.html" %}\n{% block content %}\n...\n{% endblock %}\nHowever, the
\nself.my_viewfunction registered above suffers from two\nproblems:- \n
It will not perform any permission checks, so it will be accessible\nto the general public.
\nIt will not provide any header details to prevent caching. This means\nif the page retrieves data from the database, and caching middleware is\nactive, the page could show outdated information.
\n
Since this is usually not what you want, Django provides a convenience\nwrapper to check permissions and mark the view as non-cacheable. This\nwrapper is
\nAdminSite.admin_view()(i.e.self.admin_site.admin_view\ninside aModelAdmininstance); use it like so:\nclass MyModelAdmin(admin.ModelAdmin):\n def get_urls(self):\n urls = super().get_urls()\n my_urls = [\n path('my_view/', self.admin_site.admin_view(self.my_view))\n ]\n return my_urls + urls\nNotice the wrapped view in the fifth line above:
\n\npath('my_view/', self.admin_site.admin_view(self.my_view))\nThis wrapping will protect
\nself.my_viewfrom unauthorized access and\nwill apply thedjango.views.decorators.cache.never_cache()decorator to\nmake sure it is not cached if the cache middleware is active.If the page is cacheable, but you still want the permission check to be\nperformed, you can pass a
\ncacheable=Trueargument to\nAdminSite.admin_view():\npath('my_view/', self.admin_site.admin_view(self.my_view, cacheable=True))\n
\nModelAdminviews havemodel_adminattributes. Other\nAdminSiteviews haveadmin_siteattributes.
- \n
- \nModelAdmin.get_form(request, obj=None, **kwargs)Link to this definition# \n
Returns a
\nModelFormclass for use in the admin add\nand change views, seeadd_view()andchange_view().The base implementation uses
\nmodelform_factory()\nto subclassform, modified by attributes such asfields\nandexclude. So, for example, if you wanted to offer additional\nfields to superusers, you could swap in a different base form like so:\nclass MyModelAdmin(admin.ModelAdmin):\n def get_form(self, request, obj=None, **kwargs):\n if request.user.is_superuser:\n kwargs['form'] = MySuperuserForm\n return super().get_form(request, obj, **kwargs)\nYou may also return a custom
\nModelFormclass\ndirectly.
- \n
- \nModelAdmin.get_formsets_with_inlines(request, obj=None)Link to this definition# \n
Yields (
\nFormSet,InlineModelAdmin) pairs for use in admin add\nand change views.For example if you wanted to display a particular inline only in the change\nview, you could override
\nget_formsets_with_inlinesas follows:\nclass MyModelAdmin(admin.ModelAdmin):\n inlines = [MyInline, SomeOtherInline]\n\n def get_formsets_with_inlines(self, request, obj=None):\n for inline in self.get_inline_instances(request, obj):\n # hide MyInline in the add view\n if not isinstance(inline, MyInline) or obj is not None:\n yield inline.get_formset(request, obj), inline\n
- \n
- \nModelAdmin.formfield_for_foreignkey(db_field, request, **kwargs)Link to this definition# \n
The
\nformfield_for_foreignkeymethod on aModelAdminallows you to\noverride the default formfield for a foreign keys field. For example, to\nreturn a subset of objects for this foreign key field based on the user:\nclass MyModelAdmin(admin.ModelAdmin):\n def formfield_for_foreignkey(self, db_field, request, **kwargs):\n if db_field.name == "car":\n kwargs["queryset"] = Car.objects.filter(owner=request.user)\n return super().formfield_for_foreignkey(db_field, request, **kwargs)\nThis uses the
\nHttpRequestinstance to filter theCarforeign key\nfield to only display the cars owned by theUserinstance.For more complex filters, you can use
\nModelForm.__init__()method to\nfilter based on aninstanceof your model (see\nFields which handle relationships). For example:\nclass CountryAdminForm(forms.ModelForm):\n def __init__(self, *args, **kwargs):\n super().__init__(*args, **kwargs)\n self.fields['capital'].queryset = self.instance.cities.all()\n\nclass CountryAdmin(admin.ModelAdmin):\n form = CountryAdminForm\n
- \n
- \nModelAdmin.formfield_for_manytomany(db_field, request, **kwargs)Link to this definition# \n
Like the
\nformfield_for_foreignkeymethod, the\nformfield_for_manytomanymethod can be overridden to change the\ndefault formfield for a many to many field. For example, if an owner can\nown multiple cars and cars can belong to multiple owners – a many to\nmany relationship – you could filter theCarforeign key field to\nonly display the cars owned by theUser:\nclass MyModelAdmin(admin.ModelAdmin):\n def formfield_for_manytomany(self, db_field, request, **kwargs):\n if db_field.name == "cars":\n kwargs["queryset"] = Car.objects.filter(owner=request.user)\n return super().formfield_for_manytomany(db_field, request, **kwargs)\n
- \n
- \nModelAdmin.formfield_for_choice_field(db_field, request, **kwargs)Link to this definition# \n
Like the
\nformfield_for_foreignkeyandformfield_for_manytomany\nmethods, theformfield_for_choice_fieldmethod can be overridden to\nchange the default formfield for a field that has declared choices. For\nexample, if the choices available to a superuser should be different than\nthose available to regular staff, you could proceed as follows:\n\nclass MyModelAdmin(admin.ModelAdmin):\n def formfield_for_choice_field(self, db_field, request, **kwargs):\n if db_field.name == "status":\n kwargs['choices'] = (\n ('accepted', 'Accepted'),\n ('denied', 'Denied'),\n )\n if request.user.is_superuser:\n kwargs['choices'] += (('ready', 'Ready for deployment'),)\n return super().formfield_for_choice_field(db_field, request, **kwargs)\n
- \n
- \nModelAdmin.get_changelist(request, **kwargs)Link to this definition# \n
Returns the
\nChangelistclass to be used for listing. By default,\ndjango.contrib.admin.views.main.ChangeListis used. By inheriting this\nclass you can change the behavior of the listing.
- \n
- \nModelAdmin.get_changelist_form(request, **kwargs)Link to this definition# \n
Returns a
\nModelFormclass for use in theFormset\non the changelist page. To use a custom form, for example:\n\nfrom django import forms\n\nclass MyForm(forms.ModelForm):\n pass\n\nclass MyModelAdmin(admin.ModelAdmin):\n def get_changelist_form(self, request, **kwargs):\n return MyForm\n
- \n
- \nModelAdmin.get_changelist_formset(request, **kwargs)Link to this definition# \n
Returns a ModelFormSet class for use on the\nchangelist page if
\nlist_editableis used. To use a\ncustom formset, for example:\nfrom django.forms import BaseModelFormSet\n\nclass MyAdminFormSet(BaseModelFormSet):\n pass\n\nclass MyModelAdmin(admin.ModelAdmin):\n def get_changelist_formset(self, request, **kwargs):\n kwargs['formset'] = MyAdminFormSet\n return super().get_changelist_formset(request, **kwargs)\n
- \n
- \nModelAdmin.lookup_allowed(lookup, value)Link to this definition# \n
The objects in the changelist page can be filtered with lookups from the\nURL’s query string. This is how
\nlist_filterworks, for example. The\nlookups are similar to what’s used inQuerySet.filter()(e.g.\nuser__email=user@example.com). Since the lookups in the query string\ncan be manipulated by the user, they must be sanitized to prevent\nunauthorized data exposure.The
\nlookup_allowed()method is given a lookup path from the query string\n(e.g.'user__email') and the corresponding value\n(e.g.'user@example.com'), and returns a boolean indicating whether\nfiltering the changelist’sQuerySetusing the parameters is permitted.\nIflookup_allowed()returnsFalse,DisallowedModelAdminLookup\n(subclass ofSuspiciousOperation) is raised.By default,
\nlookup_allowed()allows access to a model’s local fields,\nfield paths used inlist_filter(but not paths from\nget_list_filter()), and lookups required for\nlimit_choices_toto function\ncorrectly inraw_id_fields.Override this method to customize the lookups permitted for your\n
\nModelAdminsubclass.
- \n
- \nModelAdmin.has_view_permission(request, obj=None)Link to this definition# \n
Should return
\nTrueif viewingobjis permitted,Falseotherwise.\nIf obj isNone, should returnTrueorFalseto indicate whether\nviewing of objects of this type is permitted in general (e.g.,False\nwill be interpreted as meaning that the current user is not permitted to\nview any object of this type).The default implementation returns
\nTrueif the user has either the\n«change» or «view» permission.
- \n
- \nModelAdmin.has_add_permission(request)Link to this definition# \n
Should return
\nTrueif adding an object is permitted,False\notherwise.
- \n
- \nModelAdmin.has_change_permission(request, obj=None)Link to this definition# \n
Should return
\nTrueif editingobjis permitted,False\notherwise. IfobjisNone, should returnTrueorFalseto\nindicate whether editing of objects of this type is permitted in general\n(e.g.,Falsewill be interpreted as meaning that the current user is\nnot permitted to edit any object of this type).
- \n
- \nModelAdmin.has_delete_permission(request, obj=None)Link to this definition# \n
Should return
\nTrueif deletingobjis permitted,False\notherwise. IfobjisNone, should returnTrueorFalseto\nindicate whether deleting objects of this type is permitted in general\n(e.g.,Falsewill be interpreted as meaning that the current user is\nnot permitted to delete any object of this type).
- \n
- \nModelAdmin.has_module_permission(request)Link to this definition# \n
Should return
\nTrueif displaying the module on the admin index page and\naccessing the module’s index page is permitted,Falseotherwise.\nUsesUser.has_module_perms()by default. Overriding\nit does not restrict access to the view, add, change, or delete views,\nhas_view_permission(),\nhas_add_permission(),\nhas_change_permission(), and\nhas_delete_permission()should be used for that.
- \n
- \nModelAdmin.get_queryset(request)Link to this definition# \n
The
\nget_querysetmethod on aModelAdminreturns a\nQuerySetof all model instances that\ncan be edited by the admin site. One use case for overriding this method\nis to show objects owned by the logged-in user:\nclass MyModelAdmin(admin.ModelAdmin):\n def get_queryset(self, request):\n qs = super().get_queryset(request)\n if request.user.is_superuser:\n return qs\n return qs.filter(author=request.user)\n
- \n
- \nModelAdmin.message_user(request, message, level=messages.INFO, extra_tags='', fail_silently=False)Link to this definition# \n
Sends a message to the user using the
\ndjango.contrib.messages\nbackend. See the custom ModelAdmin example.Keyword arguments allow you to change the message level, add extra CSS\ntags, or fail silently if the
\ncontrib.messagesframework is not\ninstalled. These keyword arguments match those for\ndjango.contrib.messages.add_message(), see that function’s\ndocumentation for more details. One difference is that the level may be\npassed as a string label in addition to integer/constant.
- \n
- \nModelAdmin.get_paginator(request, queryset, per_page, orphans=0, allow_empty_first_page=True)Link to this definition# \n
Returns an instance of the paginator to use for this view. By default,\ninstantiates an instance of
\npaginator.
- \n
- \nModelAdmin.response_add(request, obj, post_url_continue=None)Link to this definition# \n
Determines the
\nHttpResponsefor the\nadd_view()stage.
\nresponse_addis called after the admin form is submitted and\njust after the object and all the related instances have\nbeen created and saved. You can override it to change the default behavior\nafter the object has been created.
- \n
- \nModelAdmin.response_change(request, obj)Link to this definition# \n
Determines the
\nHttpResponsefor the\nchange_view()stage.
\nresponse_changeis called after the admin form is submitted and\njust after the object and all the related instances have\nbeen saved. You can override it to change the default\nbehavior after the object has been changed.
- \n
- \nModelAdmin.response_delete(request, obj_display, obj_id)Link to this definition# \n
Determines the
\nHttpResponsefor the\ndelete_view()stage.
\nresponse_deleteis called after the object has been\ndeleted. You can override it to change the default\nbehavior after the object has been deleted.
\nobj_displayis a string with the name of the deleted\nobject.
\nobj_idis the serialized identifier used to retrieve the object to be\ndeleted.
- \n
- \nModelAdmin.get_changeform_initial_data(request)Link to this definition# \n
A hook for the initial data on admin change forms. By default, fields are\ngiven initial values from
\nGETparameters. For instance,\n?name=initial_valuewill set thenamefield’s initial value to be\ninitial_value.This method should return a dictionary in the form\n
\n{'fieldname': 'fieldval'}:\ndef get_changeform_initial_data(self, request):\n return {'name': 'custom_initial_value'}\n
- \n
- \nModelAdmin.get_deleted_objects(objs, request)Link to this definition# \n
A hook for customizing the deletion process of the
\ndelete_view()and\nthe «delete selected» action.The
\nobjsargument is a homogeneous iterable of objects (aQuerySet\nor a list of model instances) to be deleted, andrequestis the\nHttpRequest.This method must return a 4-tuple of\n
\n(deleted_objects, model_count, perms_needed, protected).
\ndeleted_objectsis a list of strings representing all the objects that\nwill be deleted. If there are any related objects to be deleted, the list\nis nested and includes those related objects. The list is formatted in the\ntemplate using theunordered_listfilter.
\nmodel_countis a dictionary mapping each model’s\nverbose_name_pluralto the number of\nobjects that will be deleted.
\nperms_neededis a set ofverbose_names\nof the models that the user doesn’t have permission to delete.
\nprotectedis a list of strings representing of all the protected\nrelated objects that can’t be deleted. The list is displayed in the\ntemplate.
Other methodsLink to this heading#
\n- \n
- \nModelAdmin.add_view(request, form_url='', extra_context=None)Link to this definition# \n
Django view for the model instance addition page. See note below.
\n
- \n
- \nModelAdmin.change_view(request, object_id, form_url='', extra_context=None)Link to this definition# \n
Django view for the model instance editing page. See note below.
\n
- \n
- \nModelAdmin.changelist_view(request, extra_context=None)Link to this definition# \n
Django view for the model instances change list/actions page. See note\nbelow.
\n
- \n
- \nModelAdmin.delete_view(request, object_id, extra_context=None)Link to this definition# \n
Django view for the model instance(s) deletion confirmation page. See note\nbelow.
\n
- \n
- \nModelAdmin.history_view(request, object_id, extra_context=None)Link to this definition# \n
Django view for the page that shows the modification history for a given\nmodel instance.
\n
Unlike the hook-type ModelAdmin methods detailed in the previous section,\nthese five methods are in reality designed to be invoked as Django views from\nthe admin application URL dispatching handler to render the pages that deal\nwith model instances CRUD operations. As a result, completely overriding these\nmethods will significantly change the behavior of the admin application.
One common reason for overriding these methods is to augment the context data\nthat is provided to the template that renders the view. In the following\nexample, the change view is overridden so that the rendered template is\nprovided some extra mapping data that would not otherwise be available:
\nclass MyModelAdmin(admin.ModelAdmin):\n\n # A template for a very customized change view:\n change_form_template = 'admin/myapp/extras/openstreetmap_change_form.html'\n\n def get_osm_info(self):\n # ...\n pass\n\n def change_view(self, request, object_id, form_url='', extra_context=None):\n extra_context = extra_context or {}\n extra_context['osm_data'] = self.get_osm_info()\n return super().change_view(\n request, object_id, form_url, extra_context=extra_context,\n )\nThese views return TemplateResponse\ninstances which allow you to easily customize the response data before\nrendering. For more details, see the TemplateResponse documentation.
ModelAdmin asset definitionsLink to this heading#
\nThere are times where you would like add a bit of CSS and/or JavaScript to\nthe add/change views. This can be accomplished by using a Media inner class\non your ModelAdmin:
class ArticleAdmin(admin.ModelAdmin):\n class Media:\n css = {\n "all": ("my_styles.css",)\n }\n js = ("my_code.js",)\nThe staticfiles app prepends\nSTATIC_URL (or MEDIA_URL if STATIC_URL is\nNone) to any asset paths. The same rules apply as regular asset\ndefinitions on forms.
jQueryLink to this heading#
\nDjango admin JavaScript makes use of the jQuery library.
\nTo avoid conflicts with user-supplied scripts or libraries, Django’s jQuery\n(version 3.5.1) is namespaced as django.jQuery. If you want to use jQuery\nin your own admin JavaScript without including a second copy, you can use the\ndjango.jQuery object on changelist and add/edit views. Also, your own admin\nforms or widgets depending on django.jQuery must specify\njs=['admin/js/jquery.init.js', …] when declaring form media assets.
The ModelAdmin class requires jQuery by default, so there is no need\nto add jQuery to your ModelAdmin’s list of media resources unless you have\na specific need. For example, if you require the jQuery library to be in the\nglobal namespace (for example when using third-party jQuery plugins) or if you\nneed a newer version of jQuery, you will have to include your own copy.
Django provides both uncompressed and “minified” versions of jQuery, as\njquery.js and jquery.min.js respectively.
ModelAdmin and InlineModelAdmin have a media property\nthat returns a list of Media objects which store paths to the JavaScript\nfiles for the forms and/or formsets. If DEBUG is True it will\nreturn the uncompressed versions of the various JavaScript files, including\njquery.js; if not, it will return the “minified” versions.
Adding custom validation to the adminLink to this heading#
\nYou can also add custom validation of data in the admin. The automatic admin\ninterface reuses django.forms, and the ModelAdmin class gives you\nthe ability to define your own form:
class ArticleAdmin(admin.ModelAdmin):\n form = MyArticleAdminForm\nMyArticleAdminForm can be defined anywhere as long as you import where\nneeded. Now within your form you can add your own custom validation for\nany field:
class MyArticleAdminForm(forms.ModelForm):\n def clean_name(self):\n # do something that validates your data\n return self.cleaned_data["name"]\nIt is important you use a ModelForm here otherwise things can break. See\nthe forms documentation on custom validation and, more specifically, the\nmodel form validation notes for more\ninformation.