Django Object Actions

If you've ever tried making admin object tools you may have thought, "why can't this be as easy as making Django Admin Actions?" Well now they can be.

Quick-Start Guide

Install Django Object Actions:

$ pip install django-object-actions

Add djangoobjectactions to your INSTALLED_APPS so Django can find our templates.

In your admin.py:

from djangoobjectactions import DjangoObjectActions, action
class ArticleAdmin(DjangoObjectActions, admin.ModelAdmin):     @action(label="Publish", description="Submit this article") # optional     def publish_this(self, request, obj):         publish_obj(obj)
changeactions = ("publishthis", )     changelistactions = ("actionname", )

Usage

Defining new tool actions is just like defining regular [admin actions]. The major difference is the functions for django-object-actions will take an object instance instead of a queryset (see Re-using Admin Actions below).

Tool actions are exposed by putting them in a change_actions attribute in your admin.ModelAdmin. You can also add tool actions to the main changelist views too. There, you'll get a queryset like a regular [admin action][admin actions]:

from djangoobjectactions import DjangoObjectActions
class MyModelAdmin(DjangoObjectActions, admin.ModelAdmin):     @action(         label="This will be the label of the button",  # optional         description="This will be the tooltip of the button" # optional     )     def toolfunc(self, request, obj):         pass
def make_published(modeladmin, request, queryset):         queryset.update(status='p')
change_actions = ("toolfunc", )     changelistactions = ("makepublished", )

Just like admin actions, you can send a message with self.message_user. Normally, you would do something to the object and return to the same url, but if you return a HttpResponse, it will follow it (hey, just like [admin actions]!).

If your admin modifies geturls, changeview, or changelist_view, you'll need to take extra care because django-object-actions uses them too.

Re-using Admin Actions

If you would like a preexisting admin action to also be an object action, add the takesinstanceor_queryset decorator to convert object instances into a queryset and pass querysets:

from djangoobjectactions import DjangoObjectActions, takesinstanceor_queryset
class RobotAdmin(DjangoObjectActions, admin.ModelAdmin):     # ... snip ...
@takesinstanceor_queryset     def tightenlugnuts(self, request, queryset):         queryset.update(lugnuts=F('lugnuts') - 1)
changeactions = ("tightenlug_nuts", )     actions = ("tightenlugnuts", )

[admin actions]: https://docs.djangoproject.com/en/stable/ref/contrib/admin/actions/

Customizing Object Actions

To give the action some a helpful title tooltip, you can use the action decorator and set the description argument.

@action(description="Increment the vote count by one")
def increment_vote(self, request, obj):
    obj.votes = obj.votes + 1
    obj.save()

Alternatively, you can also add a short_description attribute, similar to how admin actions work:

def increment_vote(self, request, obj):
    obj.votes = obj.votes + 1
    obj.save()
incrementvote.shortdescription = "Increment the vote count by one"

By default, Django Object Actions will guess what to label the button based on the name of the function. You can override this with a label attribute:

@action(label="Vote++")
def increment_vote(self, request, obj):
    obj.votes = obj.votes + 1
    obj.save()

or

def increment_vote(self, request, obj):
    obj.votes = obj.votes + 1
    obj.save()
increment_vote.label = "Vote++"

If you need even more control, you can add arbitrary attributes to the buttons by adding a Django widget style attrs attribute:

@action(attrs = {'class': 'addlink'})
def increment_vote(self, request, obj):
    obj.votes = obj.votes + 1
    obj.save()

or

def increment_vote(self, request, obj):
    obj.votes = obj.votes + 1
    obj.save()
increment_vote.attrs = {
    'class': 'addlink',
}

Programmatically Disabling Actions

You can programmatically disable registered actions by defining your own custom getchangeactions() method. In this example, certain actions only apply to certain object states (e.g. You should not be able to close an company account if the account is already closed):

def getchangeactions(self, request, objectid, formurl):
    actions = super(PollAdmin, self).getchangeactions(request, objectid, formurl)
    actions = list(actions)
    if not request.user.is_superuser:
        return []
obj = self.model.objects.get(pk=object_id)     if obj.question.endswith('?'):         actions.remove('question_mark')
return actions

The same is true for changelist actions with getchangelistactions.

Using POST instead of GET for actions

Since actions usually change data, for safety and semantics, it would be preferable that actions use a HTTP POST instead of a GET.

Global default (recommended)

To control default HTTP method for all actions globally, use DJANGOOBJECTACTIONSDEFAULTHTTP_METHOD in your Django settings:

# settings.py
DJANGOOBJECTACTIONSDEFAULTHTTP_METHOD = "POST"  # or "GET"

When set to "POST", action buttons will render as forms that submit via POST. When set to "GET" (or not set), actions render as regular links.

Migration note: The default will change from "GET" to "POST" in the next major version.

Per-action configuration

You can also configure individual actions to use POST:

@action(methods=("POST",), butt)
def my_action(self, request, obj):
    ...

The button_type parameter controls which kind of DOM element the button renders:

• "a" (default for GET): renders as an anchor tag/link
• "form": renders as a form that submits via POST

Alternate Installation

You don't have to add this to INSTALLED_APPS, all you need to to do is copy the template djangoobjectactions/change_form.html some place Django's template loader will find it.

If you don't intend to use the template customizations or bundled CSS at all, don't add djangoobjectactions to your INSTALLED_APPS at all and use BaseDjangoObjectActions instead of DjangoObjectActions. If you use butt actions, add this to your admin class:

class Media:
    css = {"all": ["djangoobjectactions/css/django-object-actions.css"]}

More Examples

Making an action that links off-site:

def external_link(self, request, obj):
    from django.http import HttpResponseRedirect
    return HttpResponseRedirect(f'https://example.com/{obj.id}')

Intermediate confirmation and form pages

Because an action is called with the current request, you can render a confirmation on GET and apply the change on POST. @action allows both methods by default.

from django.shortcuts import render
@action(label="Delete all choices") def deleteallchoices(self, request, obj):     if request.method == "POST":         obj.choice_set.all().delete()         return None     return render(request, "admin/confirm.html", {"object": obj})

For anything beyond a confirmation button, delegate to a FormView rather than handling the form inline. Unpacking admin.site.each_context(request) into the template context preserves the admin breadcrumbs, header, and user menu on the rendered page:

from django.contrib import admin
from django.shortcuts import redirect
from django.views.generic import FormView
from .forms import VerifyForm
class ArticleAdmin(DjangoObjectActions, admin.ModelAdmin):     @action(label="Verify")     def verify(self, request, obj):         return VerifyView.as_view()(request, target=obj)
change_actions = ("verify",)
class VerifyView(FormView):     form_class = VerifyForm     templatename = "admin/genericform.html"
def dispatch(self, request, args, target, *kwargs):         self.target = target         return super().dispatch(request, args, *kwargs)
def getcontextdata(self, **kwargs):         return {             super().getcontextdata(kwargs),             **admin.site.each_context(self.request),             "title": "Verify article",         }
def form_valid(self, form):         self.target.markasverified(**form.cleaned_data)         return redirect("admin:myapparticlechange", self.target.pk)

The template:

{% extends "admin/base_site.html" %}
{% block content %}
  <form method="POST" enctype="multipart/form-data">
    {% csrf_token %}
    {{ form.as_p }}
    <input type="submit" value="Save">
  </form>
{% endblock %}

Limitations

• django-object-actions expects functions to be methods of the model

admin. While Django gives you a lot more options for their admin actions.

• If you provide your own custom change_form.html, you'll also need

to manually copy in the relevant bits of our change form .

• Security. This has been written with the assumption that everyone in

the Django admin belongs there. Permissions should be enforced in your own actions irregardless of what this provides. Better default security is planned for the future.

Python and Django compatibility

See ci.yml for which Python and Django versions this supports.

Demo Admin

You can try the demo admin by running the example Django project in ./example_project, which is based on the "polls" tutorial. admin.py demos what you can do with this app.

Development

Getting started:

# get a copy of the code
git clone git@github.com:crccheck/django-object-actions.git
cd django-object-actions
Install requirements
make install
make test  # run test suite
make quickstart  # runs 'make resetdb' and some extra steps

Various helpers are available as make commands. Type make help and view the Makefile to see what other things you can do.

Similar Packages

Django Modal Actions can open a simple form in a modal dialog.

If you want an actions menu for each row of your changelist, check out Django Admin Row Actions.