Skip to main content

Django admin customize object tools support

Project description



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. By default this will not replace the default admin site and modeladmin, you need inherit your modeladmin class from object_tool.ObjectToolModelAdminMixin, if you still want to replace the default modeladmin, you need pass True to the register method, but we don't recommend you to do so, this have a side-effect on other apps your installed.

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.

Source Distribution

django-object-tool-0.0.11.tar.gz (15.4 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page