{"id":22206413,"url":"https://github.com/xavier-lam/django-object-tool","last_synced_at":"2025-10-28T16:32:37.400Z","repository":{"id":57421067,"uuid":"176648328","full_name":"Xavier-Lam/django-object-tool","owner":"Xavier-Lam","description":"customize django admin's object-tools bar","archived":false,"fork":false,"pushed_at":"2024-11-04T03:21:51.000Z","size":77,"stargazers_count":7,"open_issues_count":1,"forks_count":5,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-11-04T04:21:03.125Z","etag":null,"topics":["django","object-tools"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Xavier-Lam.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-03-20T03:48:48.000Z","updated_at":"2024-11-04T03:21:55.000Z","dependencies_parsed_at":"2024-11-04T04:29:58.656Z","dependency_job_id":null,"html_url":"https://github.com/Xavier-Lam/django-object-tool","commit_stats":{"total_commits":15,"total_committers":2,"mean_commits":7.5,"dds":0.06666666666666665,"last_synced_commit":"7b16dbe29d23f73633fb94da9c8f340b966ff8e4"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Xavier-Lam%2Fdjango-object-tool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Xavier-Lam%2Fdjango-object-tool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Xavier-Lam%2Fdjango-object-tool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Xavier-Lam%2Fdjango-object-tool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Xavier-Lam","download_url":"https://codeload.github.com/Xavier-Lam/django-object-tool/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227777724,"owners_count":17818455,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["django","object-tools"],"created_at":"2024-12-02T18:11:44.725Z","updated_at":"2025-10-28T16:32:37.278Z","avatar_url":"https://github.com/Xavier-Lam.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Django-object-tool\n\n[![PyPI](https://img.shields.io/pypi/v/django-object-tool.svg)](https://pypi.org/project/django-object-tool)\n[![Build Status](https://travis-ci.org/Xavier-Lam/django-object-tool.svg?branch=master)](https://travis-ci.org/Xavier-Lam/django-object-tool)\n\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.\n\n\u003e This is a pre alpha version without any unittest, there may have serveral problems and not compatible with some django or python versions.\n\n![](docs/static/images/example.jpg?raw=true)\n\n- [Quick Start](#quick-start)\n  - [Installation](#installation)\n  - [Write your first admin](#write-your-first-admin)\n  - [Specific view only object tools](#specific-view-only-object-tools)\n  - [Shortcuts](#shortcuts)\n    - [Shortcut for hyperlinks](#shortcut-for-hyperlinks)\n    - [Execute after confirmation](#execute-after-confirmation)\n    - [Create a form](#create-a-form)\n- [Advanced usage](#advanced-usage)\n  - [Site wide object tools](#site-wide-object-tools)\n  - [Work with your own admin template](#work-with-your-own-admin-template)\n  - [Use in reusable apps](#use-in-reusable-apps)\n  - [Ordering of object tools](#ordering-of-object-tools)\n  - [Customize button styles](#customize-button-styles)\n- [Configurations](#configurations)\n- [Compatibilities](#compatibilities)\n  - [django-import-export](#django-import-export)\n- [Example app](#example-app)\n- [TODOS](#todos)\n- [Change logs](#change-logs)\n  - [0.0.1](#001)\n\n## Quick Start\n### Installation\nInstall django-object-tool by using pip\n\n    pip install django-object-tool\n\nthen add it to your INSTALLED_APP\n\n    # settings\n    INSTALLED_APPS = (\n        ...\n        \"object-tool\",\n        \"your app needs object-tool\"\n    )\n\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.\n\n \u003e 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`.\n \u003e\n \u003e 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.\n\n### Write your first admin\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.\n\n    from object_tool import CustomObjectToolModelAdminMixin\n\n    class SomeModelAdmin(CustomObjectToolModelAdminMixin, admin.ModelAdmin):\n        object_tools = (\"some_action\",)\n\n        def some_action(self, request, obj=None):\n            if obj:\n                obj.some_property = \"value\"\n                obj.save()\n            else:\n                self.get_queryset(request).all().update(some_property=\"value\")\n\n\u003e 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.\n\n### Specific view only object tools\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.\n\n    from object_tool import CustomObjectToolModelAdminMixin\n\n    class SomeModelAdmin(CustomObjectToolModelAdminMixin, admin.ModelAdmin):\n        changelist_object_tools = (\"changelist_view_only_action\",)\n        change_object_tools = (\"change_view_only_action\", )\n\n### Shortcuts\n#### Shortcut for hyperlinks\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.\n\n    from object_tool import CustomObjectToolModelAdminMixin, link\n\n    class SomeModelAdmin(CustomObjectToolModelAdminMixin, admin.ModelAdmin):\n        object_tools = (\"forkme\", )\n\n        forkme = link(\n            \"https://github.com/Xavier-Lam/django-object-tool\",\n            \"Fork me on github\")\n\n#### Execute after confirmation\n    @object_tool.confirm(\"are you sure to edit %(obj)s??\", \"confirm-tool\")\n    def confirm_action(self, request, obj=None):\n        messages.success(request, \"success!\")\n\n#### Create a form\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.\n\n    from object_tool import CustomObjectToolModelAdminMixin, form\n\n    class Form(forms.Form):\n        text = forms.CharField()\n\n    class UserAdmin(CustomObjectToolModelAdminMixin, admin.ModelAdmin):\n        object_tools = (\"greetings\", )\n        \n        @form(Form, \"greetings\")\n        def greetings(self, request, form, obj=None):\n            text = form.cleaned_data[\"text\"]\n            tpl = \"greetings to {name}: {text}\"\n            if obj:\n                msg = tpl.format(name=obj.name, text=text)\n            else:\n                msg = tpl.format(name=\"all users\", text=text)\n            messages.info(request, msg)\n\n## Advanced usage\n### Site wide object tools\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.\n\n    admin_site.add_object_tool(lambda modeladmin, request, obj=None: \"some action\")\n\n\u003e Note: Apparantly, you need to set your model admin's admin_site to the above site which your object tool registered to.\n\n### Work with your own admin template\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.\n\n* admin.py\n\n        class SomeModelAdmin(CustomObjectToolModelAdminMixin, admin.ModelAdmin):\n            change_list_template = \"template.html\"\n\n* template.html\n\n        {% extends 'admin/object_tool/baseview.html' %}\n\n        ...your template code goes here...\n\n\n### Use in reusable apps\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.\n\n    class AppConfig(AppConfig):\n        name = 'app'\n\n        def ready(self):\n            import object_tool\n            object_tool.ObjectToolConfig.register()\n\n\n### Ordering of object tools\nRefer to the below table which lists the object tools' registration with the highest precedence at the top and lowest at the bottom.\n\n* admin site global tools\n* admin site global specify view tools\n* tools defined in parent model admins\n* specify view tools defined in parent model admins\n* tools defined in current model admin\n* specify view tools defined in current model admin\n\n### Customize button styles\nAssign *classes* property to object tool action can add classes to the object tool button.\n\n    def some_action(self, request, obj=None):\n        pass\n    \n    some_action.classes = \"addlink\"\n\n## Configurations\n| name | default | description |\n| --- | --- | --- |\n| OBJECT_TOOL_PATCHADMINSITE | True | replace `django.contrib.admin.sites.site` with `object_tool.CustomObjectToolAdminSite` when app loaded |\n| OBJECT_TOOL_PATCHMODELADMIN | False | replace `django.contrib.admin.options.ModelAdmin` with `object_tool.CustomObjectToolModelAdmin` when app loaded |\n\n## Compatibilities\n### django-import-export\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.\n\n## Example app\nWe provided an example app\n\n    git clone git@github.com:Xavier-Lam/django-object-tool.git\n    cd django-object-tool/example\n    pip install -r requirements.txt\n    python manage.py migrate\n    python manage.py runserver\n\nThen visit ***http://127.0.0.1:8000/admin*** and login as super admin by using account ***admin*** with password ***123456***.\n\n## TODOS\n* unittests\n* permissions\n* [django-import-export](https://github.com/django-import-export/django-import-export/tree/master/import_export) compatibility\n\n## Change logs\n### 0.0.1\n* custom object tools","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxavier-lam%2Fdjango-object-tool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxavier-lam%2Fdjango-object-tool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxavier-lam%2Fdjango-object-tool/lists"}