Django Object Tools
Django app enabling painless creation of additional admin object tools.
This packages is part of the larger Jmbo project.
Install or add
django-object-toolsto your python path.
django-object-toolsoverrides certain admin templates so you have to add it before
Call object tool's
autodiscovermethod. This works in a similar fashion as Django's admin; discovering which tools to render in admin. You can do this in any module that is called during initialization but we recommend doing it in
urls.py, as illustrated in the next point.
Hook up URLConf. Do this by pointing a given URL at the
tools.urlsmethod. In this example, we register the default
object_tools.toolsat the URL
# urls.py from django.conf.urls.defaults import * import object_tools # you can skip this if you're using Django >= 1.7 object_tools.autodiscover() urlpatterns = patterns('', (r'^object-tools/', include(object_tools.tools.urls)), )
Obviously Django Admin itself needs to be installed, as described here.
Remember to run
syncdbwhenever you install new tools to setup permissions.
django-object-tools itself doesn't do much in terms of providing useful tools. Its purpose is to simplify creation and integration of custom tools delivered by other Django applications. To that end it takes care of the messy details like permissions and admin template integration so you can focus on the fun stuff.
As an example lets create a tool allowing you to delete all objects. Yes this is a bit convoluted but it's a good toy example for illustration purposes. Have a look at django-export and django-order for examples of real world tools leveraging
Firstly create a Django app folder structure as per usual, with the root directory named
delete, including a file called
tools.py. It should look as follows:
delete/ __init__.py tools.py
tools.py to look like this:
from django.contrib.admin.actions import delete_selected import object_tools class Delete(object_tools.ObjectTool): name = 'delete' label = 'Delete all' def view(self, request, extra_context=None): queryset = self.model.objects.all() response = delete_selected(self.modeladmin, request, queryset) if response: return response else: return self.modeladmin.changelist_view(request) object_tools.tools.register(Delete)
Let's go through that line by line:
object_toolsbehaves similarly to Django's admin allowing you to explicitly register tools, see line 17. It also provides the
delete_selectedmethod provided by Django. This method will do all the heavy lifting.
- Create a tool class inheriting from
object_tools.ObjectTool. All object tools have to inherit from
ObjectToolprovides various methods to simplify creation of tools. See object_tools.options.py for more details.
- Set tool name to
delete. This has to be a unique name identifying the tool. This is used to uniquely identify the tool internally and for instance to setup permissions.
- Set label to
Delete all. The label is displayed within admin and not the name, thus allowing you to specify a more verbose, user friendly label.
viewmethod. This is the brains of your tool. The
viewmethod is called when the user executes your tool, so your tool logic would go here. This can be any view like code, as long as it returns an
HttpResponseobject. In this case we wrap Django's built-in
delete_selectedto provide the form, logic and template code to perform the actual delete.
- Register the tool with
object_tools, thus enabling its display in admin.
To enable the tool add
delete to your
Now when you navigate to the change list view of any model you'll find the delete all object tool in the upper right hand corner.
Clicking on the Delete all tool fires off the view and proceeds with deleting objects as per usual.
django-object-tools adds per tool permissions to the built-in set of default Django permissions. So in this example only superusers or users who have the the Can delete <model> permission will be able to see and use the tool. If you can't see or use a particular tool make sure the authenticated user has the required permissions to do so.