/docs/ref/contrib/admin/actions.txt

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