Skip to main content

Django admin customize object tools support

Project description


PyPI Build Status

django-object-tool let you can customize django administration's object-tools bar. You can add actions to object-tools bar beside add-object button. The definition of object-tool action are almost same as django's default action.

This is a pre alpha version without any unittest, there may have serveral problems and not compatible with some django or python versions.

Quick Start


Install django-object-tool by using pip

pip install django-object-tool

then add it to your INSTALLED_APP

# settings
    "your app needs object-tool"

All prequisites are set up! See Write your first admin to learn how to use django-object-tool in your project.

Note: We've patched django's default admin site( by default, if you want to write your own admin site, please mix object_tool.CustomObjectToolAdminSiteMixin in your admin site class or direct inherit from object_tool.CustomObjectToolAdminSite.

If you don't want to change the default site generate by django, you can set OBJECT_TOOL_PATCHADMINSITE to False in your settings file.

Write your first admin

The object tool takes a request and an optional object, when this tool called inside a change view, the current editing object will be passed in.

from object_tool import CustomObjectToolModelAdminMixin

class SomeModelAdmin(CustomObjectToolModelAdminMixin, admin.ModelAdmin):
    object_tools = ("some_action",)

    def some_action(self, request, obj=None):
        if obj:
            obj.some_property = "value"

The definition of object tool's action is almost same as django's default action, except the third parameter of the function is a optional current editing object rather than a queryset.

Specific view only object tools

You can define a object tool only show in changelist view or change view by register it to changelist_object_tools or change_object_tools in your model admin.

from object_tool import CustomObjectToolModelAdminMixin

class SomeModelAdmin(CustomObjectToolModelAdminMixin, admin.ModelAdmin):
    changelist_object_tools = ("changelist_view_only_action",)
    change_object_tools = ("change_view_only_action", )


Shortcut for hyperlinks

You can create a hyperlink object tool like add-object by using, it takes a url as the first parameter and optional short_description as the second parameter.

from object_tool import CustomObjectToolModelAdminMixin, link

class SomeModelAdmin(CustomObjectToolModelAdminMixin, admin.ModelAdmin):
    object_tools = ("forkme", )

    forkme = link(
        "Fork me on github")

Execute after confirmation

@object_tool.confirm("are you sure to edit %(obj)s??", "confirm-tool")
def confirm_action(self, request, obj=None):
    messages.success(request, "success!")

Create a form

With object_tool.form decorator, it is very easy to create a form view. This decorator takes a Form class as first parameter and it will auto render the form. When form is cleaned, it will actually execute decorated codes.

from object_tool import CustomObjectToolModelAdminMixin, form

class Form(forms.Form):
    text = forms.CharField()

class UserAdmin(CustomObjectToolModelAdminMixin, admin.ModelAdmin):
    object_tools = ("greetings", )

    @form(Form, "greetings")
    def greetings(self, request, form, obj=None):
        text = form.cleaned_data["text"]
        tpl = "greetings to {name}: {text}"
        if obj:
            msg = tpl.format(, text=text)
            msg = tpl.format(name="all users", text=text), msg)

Advanced usage

Site wide object tools

You can create a site wide object tool by register your object tool to the admin site which inherited from object_tool.CustomObjectToolAdminSiteMixin. You can set the second parameter of object_tool.CustomObjectToolAdminSiteMixin.add_object_tool to changelist or change if you want to make your object tool appear in changelist view or change view only.

admin_site.add_object_tool(lambda modeladmin, request, obj=None: "some action")

Note: Apparantly, you need to set your model admin's admin_site to the above site which your object tool registered to.

Work with your own admin template

In a object_tool.CustomObjectToolAdminSiteMixin class, rather than extends your template from admin/change_list.html or admin/change_form.html, you should extends admin/object_tool/object-tool-items.html instead.


      class SomeModelAdmin(CustomObjectToolModelAdminMixin, admin.ModelAdmin):
          change_list_template = "template.html"
  • template.html

      {% extends 'admin/object_tool/baseview.html' %}
      ...your template code goes here...

Use in reusable apps

You may run object_tool.ObjectToolConfig.register() in your reusable app's ready method. By doing this, users who use your reusable app needn't to add object_tool to their INSTALLED_APPS.

class AppConfig(AppConfig):
    name = 'app'

    def ready(self):
        import object_tool

Ordering of object tools

Refer to the below table which lists the object tools' registration with the highest precedence at the top and lowest at the bottom.

  • admin site global tools
  • admin site global specify view tools
  • tools defined in parent model admins
  • specify view tools defined in parent model admins
  • tools defined in current model admin
  • specify view tools defined in current model admin

Customize button styles

Assign classes property to object tool action can add classes to the object tool button.

def some_action(self, request, obj=None):

some_action.classes = "addlink"


name default description
OBJECT_TOOL_PATCHADMINSITE True replace with object_tool.CustomObjectToolAdminSite when app loaded
OBJECT_TOOL_PATCHMODELADMIN False replace django.contrib.admin.options.ModelAdmin with object_tool.CustomObjectToolModelAdmin when app loaded



We do not support django-import-export yet, but we have plan support django-import-export in the future.

Example app

We provided an example app

git clone
cd django-object-tool/example
pip install -r requirements.txt
python migrate
python runserver

Then visit and login as super admin by using account admin with password 123456.


Change logs


  • custom object tools

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for django-object-tool, version 0.0.7
Filename, size File type Python version Upload date Hashes
Filename, size django_object_tool-0.0.7-py2.py3-none-any.whl (17.9 kB) File type Wheel Python version py2.py3 Upload date Hashes View
Filename, size django-object-tool-0.0.7.tar.gz (13.1 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page