{"title":"Admin actions","version":"2.1","locale":"ko","docname":"ref/contrib/admin/actions","url":"/ko/2.1/ref/contrib/admin/actions/","canonical":"https://djangodocs.dev/ko/2.1/ref/contrib/admin/actions/","summary":"The basic workflow of Django’s admin is, in a nutshell, “select an object, then change it.” This works well for a majority of use cases. However, if you need to…","html":"

Admin actionsLink to this heading#

\n

The basic workflow of Django’s admin is, in a nutshell, “select an object,\nthen change it.” This works well for a majority of use cases. However, if you\nneed to make the same change to many objects at once, this workflow can be\nquite tedious.

\n

In these cases, Django’s admin lets you write and register “actions” – simple\nfunctions that get called with a list of objects selected on the change list\npage.

\n

If you look at any change list in the admin, you’ll see this feature in\naction; Django ships with a “delete selected objects” action available to all\nmodels. For example, here’s the user module from Django’s built-in\ndjango.contrib.auth app:

\n\"/ko/2.1/_images/admin-actions.png\"\n\n

Read on to find out how to add your own actions to this list.

\n
\n

Writing actionsLink to this heading#

\n

The easiest way to explain actions is by example, so let’s dive in.

\n

A common use case for admin actions is the bulk updating of a model. Imagine a\nsimple news application with an Article model:

\n
Code
from django.db import models\n\nSTATUS_CHOICES = (\n    ('d', 'Draft'),\n    ('p', 'Published'),\n    ('w', 'Withdrawn'),\n)\n\nclass Article(models.Model):\n    title = models.CharField(max_length=100)\n    body = models.TextField()\n    status = models.CharField(max_length=1, choices=STATUS_CHOICES)\n\n    def __str__(self):\n        return self.title\n
\n

A common task we might perform with a model like this is to update an\narticle’s status from “draft” to “published”. We could easily do this in the\nadmin one article at a time, but if we wanted to bulk-publish a group of\narticles, it’d be tedious. So, let’s write an action that lets us change an\narticle’s status to “published.”

\n
\n

Writing action functionsLink to this heading#

\n

First, we’ll need to write a function that gets called when the action is\ntriggered from the admin. Action functions are just regular functions that take\nthree arguments:

\n\n

Our publish-these-articles function won’t need the ModelAdmin or the\nrequest object, but we will use the queryset:

\n
Code
def make_published(modeladmin, request, queryset):\n    queryset.update(status='p')\n
\n\n

That’s actually all there is to writing an action! However, we’ll take one\nmore optional-but-useful step and give the action a “nice” title in the admin.\nBy default, this action would appear in the action list as “Make published” –\nthe function name, with underscores replaced by spaces. That’s fine, but we\ncan provide a better, more human-friendly name by giving the\nmake_published function a short_description attribute:

\n
Code
def make_published(modeladmin, request, queryset):\n    queryset.update(status='p')\nmake_published.short_description = "Mark selected stories as published"\n
\n\n
\n
\n

Adding actions to the ModelAdminLink to this heading#

\n

Next, we’ll need to inform our ModelAdmin of the action. This works\njust like any other configuration option. So, the complete admin.py with\nthe action and its registration would look like:

\n
Code
from django.contrib import admin\nfrom myapp.models import Article\n\ndef make_published(modeladmin, request, queryset):\n    queryset.update(status='p')\nmake_published.short_description = "Mark selected stories as published"\n\nclass ArticleAdmin(admin.ModelAdmin):\n    list_display = ['title', 'status']\n    ordering = ['title']\n    actions = [make_published]\n\nadmin.site.register(Article, ArticleAdmin)\n
\n

That code will give us an admin change list that looks something like this:

\n\"/ko/2.1/_images/adding-actions-to-the-modeladmin.png\"\n

That’s really all there is to it! If you’re itching to write your own actions,\nyou now know enough to get started. The rest of this document just covers more\nadvanced techniques.

\n
\n
\n

Handling errors in actionsLink to this heading#

\n

If there are foreseeable error conditions that may occur while running your\naction, you should gracefully inform the user of the problem. This means\nhandling exceptions and using\ndjango.contrib.admin.ModelAdmin.message_user() to display a user friendly\ndescription of the problem in the response.

\n
\n
\n
\n

Advanced action techniquesLink to this heading#

\n

There’s a couple of extra options and possibilities you can exploit for more\nadvanced options.

\n
\n

Actions as ModelAdmin methodsLink to this heading#

\n

The example above shows the make_published action defined as a simple\nfunction. That’s perfectly fine, but it’s not perfect from a code design point\nof view: since the action is tightly coupled to the Article object, it\nmakes sense to hook the action to the ArticleAdmin object itself.

\n

That’s easy enough to do:

\n
Code
class ArticleAdmin(admin.ModelAdmin):\n    ...\n\n    actions = ['make_published']\n\n    def make_published(self, request, queryset):\n        queryset.update(status='p')\n    make_published.short_description = "Mark selected stories as published"\n
\n

Notice first that we’ve moved make_published into a method and renamed the\nmodeladmin parameter to self, and second that we’ve now put the string\n'make_published' in actions instead of a direct function reference. This\ntells the ModelAdmin to look up the action as a method.

\n

Defining actions as methods gives the action more straightforward, idiomatic\naccess to the ModelAdmin itself, allowing the action to call any of the\nmethods provided by the admin.

\n

For example, we can use self to flash a message to the user informing her\nthat the action was successful:

\n
Code
class ArticleAdmin(admin.ModelAdmin):\n    ...\n\n    def make_published(self, request, queryset):\n        rows_updated = queryset.update(status='p')\n        if rows_updated == 1:\n            message_bit = "1 story was"\n        else:\n            message_bit = "%s stories were" % rows_updated\n        self.message_user(request, "%s successfully marked as published." % message_bit)\n
\n

This make the action match what the admin itself does after successfully\nperforming an action:

\n\"/ko/2.1/_images/actions-as-modeladmin-methods.png\"\n
\n
\n

Actions that provide intermediate pagesLink to this heading#

\n

By default, after an action is performed the user is simply redirected back\nto the original change list page. However, some actions, especially more\ncomplex ones, will need to return intermediate pages. For example, the\nbuilt-in delete action asks for confirmation before deleting the selected\nobjects.

\n

To provide an intermediary page, simply return an\nHttpResponse (or subclass) from your action. For\nexample, you might write a simple export function that uses Django’s\nserialization functions to dump some selected\nobjects as JSON:

\n
Code
from django.core import serializers\nfrom django.http import HttpResponse\n\ndef export_as_json(modeladmin, request, queryset):\n    response = HttpResponse(content_type="application/json")\n    serializers.serialize("json", queryset, stream=response)\n    return response\n
\n

Generally, something like the above isn’t considered a great idea. Most of the\ntime, the best practice will be to return an\nHttpResponseRedirect and redirect the user to a view\nyou’ve written, passing the list of selected objects in the GET query string.\nThis allows you to provide complex interaction logic on the intermediary\npages. For example, if you wanted to provide a more complete export function,\nyou’d want to let the user choose a format, and possibly a list of fields to\ninclude in the export. The best thing to do would be to write a small action\nthat simply redirects to your custom export view:

\n
Code
from django.contrib import admin\nfrom django.contrib.contenttypes.models import ContentType\nfrom django.http import HttpResponseRedirect\n\ndef export_selected_objects(modeladmin, request, queryset):\n    selected = request.POST.getlist(admin.ACTION_CHECKBOX_NAME)\n    ct = ContentType.objects.get_for_model(queryset.model)\n    return HttpResponseRedirect("/export/?ct=%s&ids=%s" % (ct.pk, ",".join(selected)))\n
\n

As you can see, the action is the simple part; all the complex logic would\nbelong in your export view. This would need to deal with objects of any type,\nhence the business with the ContentType.

\n

Writing this view is left as an exercise to the reader.

\n
\n
\n

Making actions available site-wideLink to this heading#

\n
\n
\nAdminSite.add_action(action, name=None)Link to this definition#
\n

Some actions are best if they’re made available to any object in the admin\nsite – the export action defined above would be a good candidate. You can\nmake an action globally available using AdminSite.add_action(). For\nexample:

\n
Code
from django.contrib import admin\n\nadmin.site.add_action(export_selected_objects)\n
\n

This makes the export_selected_objects action globally available as an\naction named “export_selected_objects”. You can explicitly give the action\na name – good if you later want to programmatically remove the action – by passing a second argument to\nAdminSite.add_action():

\n
Code
admin.site.add_action(export_selected_objects, 'export_selected')\n
\n
\n\n
\n
\n

Disabling actionsLink to this heading#

\n

Sometimes you need to disable certain actions – especially those\nregistered site-wide – for particular objects.\nThere’s a few ways you can disable actions:

\n
\n

Disabling a site-wide actionLink to this heading#

\n
\n
\nAdminSite.disable_action(name)Link to this definition#
\n

If you need to disable a site-wide action you can\ncall AdminSite.disable_action().

\n

For example, you can use this method to remove the built-in “delete selected\nobjects” action:

\n
Code
admin.site.disable_action('delete_selected')\n
\n

Once you’ve done the above, that action will no longer be available\nsite-wide.

\n

If, however, you need to re-enable a globally-disabled action for one\nparticular model, simply list it explicitly in your ModelAdmin.actions\nlist:

\n
Code
# Globally disable delete selected\nadmin.site.disable_action('delete_selected')\n\n# This ModelAdmin will not have delete_selected available\nclass SomeModelAdmin(admin.ModelAdmin):\n    actions = ['some_other_action']\n    ...\n\n# This one will\nclass AnotherModelAdmin(admin.ModelAdmin):\n    actions = ['delete_selected', 'a_third_action']\n    ...\n
\n
\n\n
\n
\n

Disabling all actions for a particular ModelAdminLink to this heading#

\n

If you want no bulk actions available for a given ModelAdmin, simply\nset ModelAdmin.actions to None:

\n
Code
class MyModelAdmin(admin.ModelAdmin):\n    actions = None\n
\n

This tells the ModelAdmin to not display or allow any actions,\nincluding any site-wide actions.

\n
\n
\n

Conditionally enabling or disabling actionsLink to this heading#

\n
\n
\nModelAdmin.get_actions(request)Link to this definition#
\n

Finally, you can conditionally enable or disable actions on a per-request\n(and hence per-user basis) by overriding ModelAdmin.get_actions().

\n

This returns a dictionary of actions allowed. The keys are action names, and\nthe values are (function, name, short_description) tuples.

\n

Most of the time you’ll use this method to conditionally remove actions from\nthe list gathered by the superclass. For example, if I only wanted users\nwhose names begin with ‘J’ to be able to delete objects in bulk, I could do\nthe following:

\n
Code
class MyModelAdmin(admin.ModelAdmin):\n    ...\n\n    def get_actions(self, request):\n        actions = super().get_actions(request)\n        if request.user.username[0].upper() != 'J':\n            if 'delete_selected' in actions:\n                del actions['delete_selected']\n        return actions\n
\n
\n\n
\n
\n
\n

Setting permissions for actionsLink to this heading#

\n\n

Actions may limit their availability to users with specific permissions by\nsetting an allowed_permissions attribute on the action function:

\n
Code
def make_published(modeladmin, request, queryset):\n    queryset.update(status='p')\nmake_published.allowed_permissions = ('change',)\n
\n

The make_published() action will only be available to users that pass the\nModelAdmin.has_change_permission() check.

\n

If allowed_permissions has more than one permission, the action will be\navailable as long as the user passes at least one of the checks.

\n

Available values for allowed_permissions and the corresponding method\nchecks are:

\n\n

You can specify any other value as long as you implement a corresponding\nhas_<value>_permission(self, request) method on the ModelAdmin.

\n

For example:

\n
Code
from django.contrib import admin\nfrom django.contrib.auth import get_permission_codename\n\nclass ArticleAdmin(admin.ModelAdmin):\n    actions = ['make_published']\n\n    def make_published(self, request, queryset):\n        queryset.update(status='p')\n    make_published.allowed_permissions = ('publish',)\n\n    def has_publish_permission(self, request):\n        """Does the user have the publish permission?"""\n        opts = self.opts\n        codename = get_permission_codename('publish', opts)\n        return request.user.has_perm('%s.%s' % (opts.app_label, codename))\n
\n
\n
","rootId":"admin-actions","toc":[{"title":"Writing actions","anchor":"writing-actions","children":[{"title":"Writing action functions","anchor":"writing-action-functions","children":[]},{"title":"Adding actions to the ModelAdmin","anchor":"adding-actions-to-the-modeladmin","children":[]},{"title":"Handling errors in actions","anchor":"handling-errors-in-actions","children":[]}]},{"title":"Advanced action techniques","anchor":"advanced-action-techniques","children":[{"title":"Actions as ModelAdmin methods","anchor":"actions-as-modeladmin-methods","children":[]},{"title":"Actions that provide intermediate pages","anchor":"actions-that-provide-intermediate-pages","children":[]},{"title":"Making actions available site-wide","anchor":"making-actions-available-site-wide","children":[]},{"title":"Disabling actions","anchor":"disabling-actions","children":[{"title":"Disabling a site-wide action","anchor":"disabling-a-site-wide-action","children":[]},{"title":"Disabling all actions for a particular ModelAdmin","anchor":"disabling-all-actions-for-a-particular-modeladmin","children":[]},{"title":"Conditionally enabling or disabling actions","anchor":"conditionally-enabling-or-disabling-actions","children":[]}]},{"title":"Setting permissions for actions","anchor":"setting-permissions-for-actions","children":[]}]}],"breadcrumbs":[{"docname":"ref/index","title":"API Reference","url":"/ko/2.1/ref/"},{"docname":"ref/contrib/index","title":"contrib packages","url":"/ko/2.1/ref/contrib/"},{"docname":"ref/contrib/admin/index","title":"The Django admin site","url":"/ko/2.1/ref/contrib/admin/"}],"prev":{"docname":"ref/contrib/admin/index","title":"The Django admin site","url":"/ko/2.1/ref/contrib/admin/"},"next":{"docname":"ref/contrib/admin/admindocs","title":"The Django admin documentation generator","url":"/ko/2.1/ref/contrib/admin/admindocs/"},"formats":{"html":"/ko/2.1/ref/contrib/admin/actions/","markdown":"/ko/2.1/ref/contrib/admin/actions.md","json":"/ko/2.1/ref/contrib/admin/actions.json"},"source":"https://github.com/django/django/blob/stable/2.1.x/docs/ref/contrib/admin/actions.txt","official":"https://docs.djangoproject.com/ko/2.1/ref/contrib/admin/actions/","inVersions":["6.1","6.0","5.2","5.1","5.0","4.2","4.1","4.0","3.2","3.1","3.0","2.2","2.1","2.0","1.11"],"inLocales":["en","zh-hans","fr","ja","id","pt-br","ko","es","el","pl"]}