/docs/ref/contrib/admin/actions.txt
Plain Text | 349 lines | 249 code | 100 blank | 0 comment | 0 complexity | d0e3ed5f62a6213b6a4e89426816da15 MD5 | raw file
Possible License(s): BSD-3-Clause
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