Django admin customize object tools support
Project description
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
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 mixobject_tool.CustomObjectToolAdminSiteMixin
in your admin site class or direct inherit fromobject_tool.CustomObjectToolAdminSite
.
If you don't want to change the default site generate by django, you can set
OBJECT_TOOL_PATCHADMINSITE
toFalse
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
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Hashes for django-object-tool-0.0.11.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | f5727463a9345ace226a5b5b3259097968037b801365f0feff4ec141fd658700 |
|
MD5 | 1d4783098f93a25b44a244af9da2d484 |
|
BLAKE2b-256 | 5036fbc45e0495cdaeff7a2575b9896fab9f96460c572be5d410010cd5ff29c6 |