Admin actions¶

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 make the same change to many objects at once, this workflow can be quite tedious.

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

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

Warning The “delete selected objects” action uses QuerySet.delete() for efficiency reasons, which has an important caveat: your model’s delete() method will not be called. If you wish to override this behavior, you can override ModelAdmin.delete_queryset() or write a custom action which does deletion in your preferred manner – for example, by calling Model.delete() for each of the selected items. For more background on bulk deletion, see the documentation on object deletion.

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

Writing actions¶ The easiest way to explain actions is by example, so let’s dive in. A common use case for admin actions is the bulk updating of a model. Imagine a news application with an Article model: from django.db import models STATUS_CHOICES = [ ( 'd' , 'Draft' ), ( 'p' , 'Published' ), ( 'w' , 'Withdrawn' ), ] class Article ( models . Model ): title = models . CharField ( max_length = 100 ) body = models . TextField () status = models . CharField ( max_length = 1 , choices = STATUS_CHOICES ) def __str__ ( self ): return self . title A common task we might perform with a model like this is to update an article’s status from “draft” to “published”. We could easily do this in the admin one article at a time, but if we wanted to bulk-publish a group of articles, it’d be tedious. So, let’s write an action that lets us change an article’s status to “published.” Writing action functions¶ First, we’ll need to write a function that gets called when the action is triggered from the admin. Action functions are regular functions that take three arguments: The current ModelAdmin

An HttpRequest representing the current request,

representing the current request, A QuerySet containing the set of objects selected by the user. Our publish-these-articles function won’t need the ModelAdmin or the request object, but we will use the queryset: def make_published ( modeladmin , request , queryset ): queryset . update ( status = 'p' ) Note For the best performance, we’re using the queryset’s update method. Other types of actions might need to deal with each object individually; in these cases we’d iterate over the queryset: for obj in queryset : do_something_with ( obj ) That’s actually all there is to writing an action! However, we’ll take one more optional-but-useful step and give the action a “nice” title in the admin. By default, this action would appear in the action list as “Make published” – the function name, with underscores replaced by spaces. That’s fine, but we can provide a better, more human-friendly name by giving the make_published function a short_description attribute: def make_published ( modeladmin , request , queryset ): queryset . update ( status = 'p' ) make_published . short_description = "Mark selected stories as published" Note This might look familiar; the admin’s list_display option uses the same technique to provide human-readable descriptions for callback functions registered there, too. Adding actions to the ModelAdmin ¶ Next, we’ll need to inform our ModelAdmin of the action. This works just like any other configuration option. So, the complete admin.py with the action and its registration would look like: from django.contrib import admin from myapp.models import Article def make_published ( modeladmin , request , queryset ): queryset . update ( status = 'p' ) make_published . short_description = "Mark selected stories as published" class ArticleAdmin ( admin . ModelAdmin ): list_display = [ 'title' , 'status' ] ordering = [ 'title' ] actions = [ make_published ] admin . site . register ( Article , ArticleAdmin ) That code will give us an admin change list that looks something like this: That’s really all there is to it! If you’re itching to write your own actions, you now know enough to get started. The rest of this document covers more advanced techniques. Handling errors in actions¶ If there are foreseeable error conditions that may occur while running your action, you should gracefully inform the user of the problem. This means handling exceptions and using django.contrib.admin.ModelAdmin.message_user() to display a user friendly description of the problem in the response.