# Django-object-tool
[](https://pypi.org/project/django-object-tool)
[](https://travis-ci.org/Xavier-Lam/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](#quick-start)
- [Installation](#installation)
- [Write your first admin](#write-your-first-admin)
- [Specific view only object tools](#specific-view-only-object-tools)
- [Shortcuts](#shortcuts)
- [Shortcut for hyperlinks](#shortcut-for-hyperlinks)
- [Execute after confirmation](#execute-after-confirmation)
- [Create a form](#create-a-form)
- [Advanced usage](#advanced-usage)
- [Site wide object tools](#site-wide-object-tools)
- [Work with your own admin template](#work-with-your-own-admin-template)
- [Use in reusable apps](#use-in-reusable-apps)
- [Ordering of object tools](#ordering-of-object-tools)
- [Customize button styles](#customize-button-styles)
- [Configurations](#configurations)
- [Compatibilities](#compatibilities)
- [django-import-export](#django-import-export)
- [Example app](#example-app)
- [TODOS](#todos)
- [Change logs](#change-logs)
- [0.0.1](#001)
## 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](#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](https://github.com/django-import-export/django-import-export/tree/master/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](https://github.com/django-import-export/django-import-export/tree/master/import_export) compatibility
## Change logs
### 0.0.1
* custom object tools
Raw data
{
"_id": null,
"home_page": "https://github.com/Xavier-Lam/django-object-tool",
"name": "django-object-tool",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "django,object-tool,object-tools,administration",
"author": "Xavier-Lam",
"author_email": "Lam.Xavier@hotmail.com",
"download_url": "https://files.pythonhosted.org/packages/50/36/fbc45e0495cdaeff7a2575b9896fab9f96460c572be5d410010cd5ff29c6/django-object-tool-0.0.11.tar.gz",
"platform": null,
"description": "# Django-object-tool\r\r\n\r\r\n[](https://pypi.org/project/django-object-tool)\r\r\n[](https://travis-ci.org/Xavier-Lam/django-object-tool)\r\r\n\r\r\n**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.\r\r\n\r\r\n> This is a pre alpha version without any unittest, there may have serveral problems and not compatible with some django or python versions.\r\r\n\r\r\n\r\r\n\r\r\n- [Quick Start](#quick-start)\r\r\n - [Installation](#installation)\r\r\n - [Write your first admin](#write-your-first-admin)\r\r\n - [Specific view only object tools](#specific-view-only-object-tools)\r\r\n - [Shortcuts](#shortcuts)\r\r\n - [Shortcut for hyperlinks](#shortcut-for-hyperlinks)\r\r\n - [Execute after confirmation](#execute-after-confirmation)\r\r\n - [Create a form](#create-a-form)\r\r\n- [Advanced usage](#advanced-usage)\r\r\n - [Site wide object tools](#site-wide-object-tools)\r\r\n - [Work with your own admin template](#work-with-your-own-admin-template)\r\r\n - [Use in reusable apps](#use-in-reusable-apps)\r\r\n - [Ordering of object tools](#ordering-of-object-tools)\r\r\n - [Customize button styles](#customize-button-styles)\r\r\n- [Configurations](#configurations)\r\r\n- [Compatibilities](#compatibilities)\r\r\n - [django-import-export](#django-import-export)\r\r\n- [Example app](#example-app)\r\r\n- [TODOS](#todos)\r\r\n- [Change logs](#change-logs)\r\r\n - [0.0.1](#001)\r\r\n\r\r\n## Quick Start\r\r\n### Installation\r\r\nInstall django-object-tool by using pip\r\r\n\r\r\n pip install django-object-tool\r\r\n\r\r\nthen add it to your INSTALLED_APP\r\r\n\r\r\n # settings\r\r\n INSTALLED_APPS = (\r\r\n ...\r\r\n \"object-tool\",\r\r\n \"your app needs object-tool\"\r\r\n )\r\r\n\r\r\nAll prequisites are set up! See [Write your first admin](#Write-your-first-admin) to learn how to use django-object-tool in your project.\r\r\n\r\r\n > 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`.\r\r\n >\r\r\n > 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.\r\r\n\r\r\n### Write your first admin\r\r\nThe 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.\r\r\n\r\r\n from object_tool import CustomObjectToolModelAdminMixin\r\r\n\r\r\n class SomeModelAdmin(CustomObjectToolModelAdminMixin, admin.ModelAdmin):\r\r\n object_tools = (\"some_action\",)\r\r\n\r\r\n def some_action(self, request, obj=None):\r\r\n if obj:\r\r\n obj.some_property = \"value\"\r\r\n obj.save()\r\r\n else:\r\r\n self.get_queryset(request).all().update(some_property=\"value\")\r\r\n\r\r\n> 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.\r\r\n\r\r\n### Specific view only object tools\r\r\nYou 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.\r\r\n\r\r\n from object_tool import CustomObjectToolModelAdminMixin\r\r\n\r\r\n class SomeModelAdmin(CustomObjectToolModelAdminMixin, admin.ModelAdmin):\r\r\n changelist_object_tools = (\"changelist_view_only_action\",)\r\r\n change_object_tools = (\"change_view_only_action\", )\r\r\n\r\r\n### Shortcuts\r\r\n#### Shortcut for hyperlinks\r\r\nYou 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.\r\r\n\r\r\n from object_tool import CustomObjectToolModelAdminMixin, link\r\r\n\r\r\n class SomeModelAdmin(CustomObjectToolModelAdminMixin, admin.ModelAdmin):\r\r\n object_tools = (\"forkme\", )\r\r\n\r\r\n forkme = link(\r\r\n \"https://github.com/Xavier-Lam/django-object-tool\",\r\r\n \"Fork me on github\")\r\r\n\r\r\n#### Execute after confirmation\r\r\n @object_tool.confirm(\"are you sure to edit %(obj)s??\", \"confirm-tool\")\r\r\n def confirm_action(self, request, obj=None):\r\r\n messages.success(request, \"success!\")\r\r\n\r\r\n#### Create a form\r\r\nWith `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.\r\r\n\r\r\n from object_tool import CustomObjectToolModelAdminMixin, form\r\r\n\r\r\n class Form(forms.Form):\r\r\n text = forms.CharField()\r\r\n\r\r\n class UserAdmin(CustomObjectToolModelAdminMixin, admin.ModelAdmin):\r\r\n object_tools = (\"greetings\", )\r\r\n \r\r\n @form(Form, \"greetings\")\r\r\n def greetings(self, request, form, obj=None):\r\r\n text = form.cleaned_data[\"text\"]\r\r\n tpl = \"greetings to {name}: {text}\"\r\r\n if obj:\r\r\n msg = tpl.format(name=obj.name, text=text)\r\r\n else:\r\r\n msg = tpl.format(name=\"all users\", text=text)\r\r\n messages.info(request, msg)\r\r\n\r\r\n## Advanced usage\r\r\n### Site wide object tools\r\r\nYou 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.\r\r\n\r\r\n admin_site.add_object_tool(lambda modeladmin, request, obj=None: \"some action\")\r\r\n\r\r\n> Note: Apparantly, you need to set your model admin's admin_site to the above site which your object tool registered to.\r\r\n\r\r\n### Work with your own admin template\r\r\n 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.\r\r\n\r\r\n* admin.py\r\r\n\r\r\n class SomeModelAdmin(CustomObjectToolModelAdminMixin, admin.ModelAdmin):\r\r\n change_list_template = \"template.html\"\r\r\n\r\r\n* template.html\r\r\n\r\r\n {% extends 'admin/object_tool/baseview.html' %}\r\r\n\r\r\n ...your template code goes here...\r\r\n\r\r\n\r\r\n### Use in reusable apps\r\r\nYou 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.\r\r\n\r\r\n class AppConfig(AppConfig):\r\r\n name = 'app'\r\r\n\r\r\n def ready(self):\r\r\n import object_tool\r\r\n object_tool.ObjectToolConfig.register()\r\r\n\r\r\n\r\r\n### Ordering of object tools\r\r\nRefer to the below table which lists the object tools' registration with the highest precedence at the top and lowest at the bottom.\r\r\n\r\r\n* admin site global tools\r\r\n* admin site global specify view tools\r\r\n* tools defined in parent model admins\r\r\n* specify view tools defined in parent model admins\r\r\n* tools defined in current model admin\r\r\n* specify view tools defined in current model admin\r\r\n\r\r\n### Customize button styles\r\r\nAssign *classes* property to object tool action can add classes to the object tool button.\r\r\n\r\r\n def some_action(self, request, obj=None):\r\r\n pass\r\r\n \r\r\n some_action.classes = \"addlink\"\r\r\n\r\r\n## Configurations\r\r\n| name | default | description |\r\r\n| --- | --- | --- |\r\r\n| OBJECT_TOOL_PATCHADMINSITE | True | replace `django.contrib.admin.sites.site` with `object_tool.CustomObjectToolAdminSite` when app loaded |\r\r\n| OBJECT_TOOL_PATCHMODELADMIN | False | replace `django.contrib.admin.options.ModelAdmin` with `object_tool.CustomObjectToolModelAdmin` when app loaded |\r\r\n\r\r\n## Compatibilities\r\r\n### django-import-export\r\r\nWe do not support [django-import-export](https://github.com/django-import-export/django-import-export/tree/master/import_export) yet, but we have plan support django-import-export in the future.\r\r\n\r\r\n## Example app\r\r\nWe provided an example app\r\r\n\r\r\n git clone git@github.com:Xavier-Lam/django-object-tool.git\r\r\n cd django-object-tool/example\r\r\n pip install -r requirements.txt\r\r\n python manage.py migrate\r\r\n python manage.py runserver\r\r\n\r\r\nThen visit ***http://127.0.0.1:8000/admin*** and login as super admin by using account ***admin*** with password ***123456***.\r\r\n\r\r\n## TODOS\r\r\n* unittests\r\r\n* permissions\r\r\n* [django-import-export](https://github.com/django-import-export/django-import-export/tree/master/import_export) compatibility\r\r\n\r\r\n## Change logs\r\r\n### 0.0.1\r\r\n* custom object tools\r\n",
"bugtrack_url": null,
"license": "",
"summary": "Django admin customize object tools support",
"version": "0.0.11",
"project_urls": {
"Homepage": "https://github.com/Xavier-Lam/django-object-tool"
},
"split_keywords": [
"django",
"object-tool",
"object-tools",
"administration"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5036fbc45e0495cdaeff7a2575b9896fab9f96460c572be5d410010cd5ff29c6",
"md5": "1d4783098f93a25b44a244af9da2d484",
"sha256": "f5727463a9345ace226a5b5b3259097968037b801365f0feff4ec141fd658700"
},
"downloads": -1,
"filename": "django-object-tool-0.0.11.tar.gz",
"has_sig": false,
"md5_digest": "1d4783098f93a25b44a244af9da2d484",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 15395,
"upload_time": "2023-08-18T10:08:36",
"upload_time_iso_8601": "2023-08-18T10:08:36.713909Z",
"url": "https://files.pythonhosted.org/packages/50/36/fbc45e0495cdaeff7a2575b9896fab9f96460c572be5d410010cd5ff29c6/django-object-tool-0.0.11.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-18 10:08:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Xavier-Lam",
"github_project": "django-object-tool",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"requirements": [],
"tox": true,
"lcname": "django-object-tool"
}
JSON
