Django-object-tool

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

  • Installation

  • Write your first admin

  • Specific view only object tools

  • Shortcuts

    • Shortcut for hyperlinks

    • Execute after confirmation

    • Create a form

• Advanced usage

  • Site wide object tools

  • Work with your own admin template

  • Use in reusable apps

  • Ordering of object tools

  • Customize button styles

• Configurations

• Compatibilities

  • django-import-export

• Example app

• TODOS

• Change logs

  • 0.0.1

Quick Start

Installation

Install django-object-tool by using pip

pip install django-object-tool

then add it to your INSTALLED_APP

# settings

INSTALLED_APPS = (

    ...

    "object-tool",

    "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(django.contrib.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"

            obj.save()

        else:

            self.get_queryset(request).all().update(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", )

Shortcuts

Shortcut for hyperlinks

You can create a hyperlink object tool like add-object by using object_tool.link, 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(

        "https://github.com/Xavier-Lam/django-object-tool",

        "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(name=obj.name, text=text)

        else:

            msg = tpl.format(name="all users", text=text)

        messages.info(request, 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.

• admin.py

    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

        object_tool.ObjectToolConfig.register()

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):

    pass



some_action.classes = "addlink"

Configurations

| name | default | description |

| --- | --- | --- |

| OBJECT_TOOL_PATCHADMINSITE | True | replace django.contrib.admin.sites.site with object_tool.CustomObjectToolAdminSite when app loaded |

| OBJECT_TOOL_PATCHMODELADMIN | False | replace django.contrib.admin.options.ModelAdmin with object_tool.CustomObjectToolModelAdmin when app loaded |

Compatibilities

django-import-export

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 git@github.com:Xavier-Lam/django-object-tool.git

cd django-object-tool/example

pip install -r requirements.txt

python manage.py migrate

python manage.py runserver

Then visit http://127.0.0.1:8000/admin and login as super admin by using account admin with password 123456.

TODOS

• unittests

• permissions

• django-import-export compatibility

Change logs

0.0.1

• custom object tools