1 .. _ref-contrib-admin-actions:
9 .. currentmodule:: django.contrib.admin
11 The basic workflow of Django's admin is, in a nutshell, "select an object,
12 then change it." This works well for a majority of use cases. However, if you
13 need to make the same change to many objects at once, this workflow can be
16 In these cases, Django's admin lets you write and register "actions" -- simple
17 functions that get called with a list of objects selected on the change list
20 If you look at any change list in the admin, you'll see this feature in
21 action; Django ships with a "delete selected objects" action available to all
22 models. For example, here's the user module from Django's built-in
23 :mod:`django.contrib.auth` app:
25 .. image:: _images/user_actions.png
29 The "delete selected objects" action uses :meth:`QuerySet.delete()
30 <django.db.models.QuerySet.delete>` for efficiency reasons, which has an
31 important caveat: your model's ``delete()`` method will not be called.
33 If you wish to override this behavior, simply write a custom action which
34 accomplishes deletion in your preferred manner -- for example, by calling
35 ``Model.delete()`` for each of the selected items.
37 For more background on bulk deletion, see the documentation on :ref:`object
38 deletion <topics-db-queries-delete>`.
40 Read on to find out how to add your own actions to this list.
45 The easiest way to explain actions is by example, so let's dive in.
47 A common use case for admin actions is the bulk updating of a model. Imagine a
48 simple news application with an ``Article`` model::
50 from django.db import models
58 class Article(models.Model):
59 title = models.CharField(max_length=100)
60 body = models.TextField()
61 status = models.CharField(max_length=1, choices=STATUS_CHOICES)
63 def __unicode__(self):
66 A common task we might perform with a model like this is to update an
67 article's status from "draft" to "published". We could easily do this in the
68 admin one article at a time, but if we wanted to bulk-publish a group of
69 articles, it'd be tedious. So, let's write an action that lets us change an
70 article's status to "published."
72 Writing action functions
73 ------------------------
75 First, we'll need to write a function that gets called when the action is
76 trigged from the admin. Action functions are just regular functions that take
79 * The current :class:`ModelAdmin`
80 * An :class:`~django.http.HttpRequest` representing the current request,
81 * A :class:`~django.db.models.QuerySet` containing the set of objects
84 Our publish-these-articles function won't need the :class:`ModelAdmin` or the
85 request object, but we will use the queryset::
87 def make_published(modeladmin, request, queryset):
88 queryset.update(status='p')
92 For the best performance, we're using the queryset's :ref:`update method
93 <topics-db-queries-update>`. Other types of actions might need to deal
94 with each object individually; in these cases we'd just iterate over the
98 do_something_with(obj)
100 That's actually all there is to writing an action! However, we'll take one
101 more optional-but-useful step and give the action a "nice" title in the admin.
102 By default, this action would appear in the action list as "Make published" --
103 the function name, with underscores replaced by spaces. That's fine, but we
104 can provide a better, more human-friendly name by giving the
105 ``make_published`` function a ``short_description`` attribute::
107 def make_published(modeladmin, request, queryset):
108 queryset.update(status='p')
109 make_published.short_description = "Mark selected stories as published"
113 This might look familiar; the admin's ``list_display`` option uses the
114 same technique to provide human-readable descriptions for callback
115 functions registered there, too.
117 Adding actions to the :class:`ModelAdmin`
118 -----------------------------------------
120 Next, we'll need to inform our :class:`ModelAdmin` of the action. This works
121 just like any other configuration option. So, the complete ``admin.py`` with
122 the action and its registration would look like::
124 from django.contrib import admin
125 from myapp.models import Article
127 def make_published(modeladmin, request, queryset):
128 queryset.update(status='p')
129 make_published.short_description = "Mark selected stories as published"
131 class ArticleAdmin(admin.ModelAdmin):
132 list_display = ['title', 'status']
134 actions = [make_published]
136 admin.site.register(Article, ArticleAdmin)
138 That code will give us an admin change list that looks something like this:
140 .. image:: _images/article_actions.png
142 That's really all there is to it! If you're itching to write your own actions,
143 you now know enough to get started. The rest of this document just covers more
146 Advanced action techniques
147 ==========================
149 There's a couple of extra options and possibilities you can exploit for more
152 Actions as :class:`ModelAdmin` methods
153 --------------------------------------
155 The example above shows the ``make_published`` action defined as a simple
156 function. That's perfectly fine, but it's not perfect from a code design point
157 of view: since the action is tightly coupled to the ``Article`` object, it
158 makes sense to hook the action to the ``ArticleAdmin`` object itself.
160 That's easy enough to do::
162 class ArticleAdmin(admin.ModelAdmin):
165 actions = ['make_published']
167 def make_published(self, request, queryset):
168 queryset.update(status='p')
169 make_published.short_description = "Mark selected stories as published"
171 Notice first that we've moved ``make_published`` into a method and renamed the
172 `modeladmin` parameter to `self`, and second that we've now put the string
173 ``'make_published'`` in ``actions`` instead of a direct function reference. This
174 tells the :class:`ModelAdmin` to look up the action as a method.
176 Defining actions as methods gives the action more straightforward, idiomatic
177 access to the :class:`ModelAdmin` itself, allowing the action to call any of the
178 methods provided by the admin.
180 For example, we can use ``self`` to flash a message to the user informing her
181 that the action was successful::
183 class ArticleAdmin(admin.ModelAdmin):
186 def make_published(self, request, queryset):
187 rows_updated = queryset.update(status='p')
188 if rows_updated == 1:
189 message_bit = "1 story was"
191 message_bit = "%s stories were" % rows_updated
192 self.message_user(request, "%s successfully marked as published." % message_bit)
194 This make the action match what the admin itself does after successfully
195 performing an action:
197 .. image:: _images/article_actions_message.png
199 Actions that provide intermediate pages
200 ---------------------------------------
202 By default, after an action is performed the user is simply redirected back
203 to the original change list page. However, some actions, especially more
204 complex ones, will need to return intermediate pages. For example, the
205 built-in delete action asks for confirmation before deleting the selected
208 To provide an intermediary page, simply return an
209 :class:`~django.http.HttpResponse` (or subclass) from your action. For
210 example, you might write a simple export function that uses Django's
211 :ref:`serialization functions <topics-serialization>` to dump some selected
214 from django.http import HttpResponse
215 from django.core import serializers
217 def export_as_json(modeladmin, request, queryset):
218 response = HttpResponse(mimetype="text/javascript")
219 serializers.serialize("json", queryset, stream=response)
222 Generally, something like the above isn't considered a great idea. Most of the
223 time, the best practice will be to return an
224 :class:`~django.http.HttpResponseRedirect` and redirect the user to a view
225 you've written, passing the list of selected objects in the GET query string.
226 This allows you to provide complex interaction logic on the intermediary
227 pages. For example, if you wanted to provide a more complete export function,
228 you'd want to let the user choose a format, and possibly a list of fields to
229 include in the export. The best thing to do would be to write a small action
230 that simply redirects to your custom export view::
232 from django.contrib import admin
233 from django.contrib.contenttypes.models import ContentType
234 from django.http import HttpResponseRedirect
236 def export_selected_objects(modeladmin, request, queryset):
237 selected = request.POST.getlist(admin.ACTION_CHECKBOX_NAME)
238 ct = ContentType.objects.get_for_model(queryset.model)
239 return HttpResponseRedirect("/export/?ct=%s&ids=%s" % (ct.pk, ",".join(selected)))
241 As you can see, the action is the simple part; all the complex logic would
242 belong in your export view. This would need to deal with objects of any type,
243 hence the business with the ``ContentType``.
245 Writing this view is left as an exercise to the reader.
247 .. _adminsite-actions:
249 Making actions available site-wide
250 ----------------------------------
252 .. method:: AdminSite.add_action(action[, name])
254 Some actions are best if they're made available to *any* object in the admin
255 site -- the export action defined above would be a good candidate. You can
256 make an action globally available using :meth:`AdminSite.add_action()`. For
259 from django.contrib import admin
261 admin.site.add_action(export_selected_objects)
263 This makes the `export_selected_objects` action globally available as an
264 action named `"export_selected_objects"`. You can explicitly give the action
265 a name -- good if you later want to programatically :ref:`remove the action
266 <disabling-admin-actions>` -- by passing a second argument to
267 :meth:`AdminSite.add_action()`::
269 admin.site.add_action(export_selected_objects, 'export_selected')
271 .. _disabling-admin-actions:
276 Sometimes you need to disable certain actions -- especially those
277 :ref:`registered site-wide <adminsite-actions>` -- for particular objects.
278 There's a few ways you can disable actions:
280 Disabling a site-wide action
281 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
283 .. method:: AdminSite.disable_action(name)
285 If you need to disable a :ref:`site-wide action <adminsite-actions>` you can
286 call :meth:`AdminSite.disable_action()`.
288 For example, you can use this method to remove the built-in "delete selected
291 admin.site.disable_action('delete_selected')
293 Once you've done the above, that action will no longer be available
296 If, however, you need to re-enable a globally-disabled action for one
297 particular model, simply list it explicitally in your ``ModelAdmin.actions``
300 # Globally disable delete selected
301 admin.site.disable_action('delete_selected')
303 # This ModelAdmin will not have delete_selected available
304 class SomeModelAdmin(admin.ModelAdmin):
305 actions = ['some_other_action']
309 class AnotherModelAdmin(admin.ModelAdmin):
310 actions = ['delete_selected', 'a_third_action']
314 Disabling all actions for a particular :class:`ModelAdmin`
315 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
317 If you want *no* bulk actions available for a given :class:`ModelAdmin`, simply
318 set :attr:`ModelAdmin.actions` to ``None``::
320 class MyModelAdmin(admin.ModelAdmin):
323 This tells the :class:`ModelAdmin` to not display or allow any actions,
324 including any :ref:`site-wide actions <adminsite-actions>`.
326 Conditionally enabling or disabling actions
327 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
329 .. method:: ModelAdmin.get_actions(request)
331 Finally, you can conditionally enable or disable actions on a per-request
332 (and hence per-user basis) by overriding :meth:`ModelAdmin.get_actions`.
334 This returns a dictionary of actions allowed. The keys are action names, and
335 the values are ``(function, name, short_description)`` tuples.
337 Most of the time you'll use this method to conditionally remove actions from
338 the list gathered by the superclass. For example, if I only wanted users
339 whose names begin with 'J' to be able to delete objects in bulk, I could do
342 class MyModelAdmin(admin.ModelAdmin):
345 def get_actions(self, request):
346 actions = super(MyModelAdmin, self).get_actions(request)
347 if request.user.username[0].upper() != 'J':
348 del actions['delete_selected']