Metadata-Version: 2.1
Name: django-object-tool
Version: 0.0.10
Summary: Django admin customize object tools support
Home-page: https://github.com/Xavier-Lam/django-object-tool
Author: Xavier-Lam
Author-email: Lam.Xavier@hotmail.com
License: UNKNOWN
Description: # Django-object-tool
        
        [![PyPI](https://img.shields.io/pypi/v/django-object-tool.svg)](https://pypi.org/project/django-object-tool)
        [![Build Status](https://travis-ci.org/Xavier-Lam/django-object-tool.svg?branch=master)](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.
        
        ![](docs/static/images/example.jpg?raw=true)
        
        - [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
Keywords: django,object-tool,object-tools,administration
Platform: UNKNOWN
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Environment :: Web Environment
Classifier: Framework :: Django :: 1.11
Classifier: Framework :: Django :: 2.0
Classifier: Framework :: Django :: 2.1
Classifier: Framework :: Django :: 2.2
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Internet :: WWW/HTTP :: Site Management
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Description-Content-Type: text/markdown
