Adding Custom Actions To Django Admin Change Forms

« Shark Or Bear – Its A Killer Website | Home | When Django Apps Grow Up »

Adding Custom Actions To Django Admin Change Forms

By Paul Kenjora | November 7, 2007

I recently had a problem where I needed to add a custom action next to "History" and "View on site" in the Django admin change form for a specific model. Normally I would overload the admin template. Problem is I wanted to retain "History" and "View". The approach I took was to extend the model interface just like "search_fields" and "list_filter". This required surprisingly little modification of the framework as I followed mostly the models already there. To my surprise the pieces fit really nicely, existing "History" and "View" links work pretty much the same way, I just defined a customizable list. I implemented in 0.95 but it works just as well in 0.96 and up.

What is It

In short the ability to add any action to the top of any admin change form that links to a custom URL of your choosing, it even passes the model and object id. You could use this for things like "Email To Admin" or "Scrape From Some Place". Typically I envision short scripts that refresh or distribute the object to third parties and then return back to the editing page.

Model Interface

Custom actions are added though the model definition. To create a custom action simply add it to the list "form_actions". The action consists of a URL tag, in this case "email", which is used in the redirect and a label, in this case "Email HR". A complete example below…

Custom Action Handlers

The handler for a custom action can be any regular Django URL handler as defined in "urls.py". No fear, this is business as usual, just make sure to define a URL pattern according to "admin/[tag]/\d+/(?P\d+)/$" where [tag] was given in the model.

Technically thats all you need to do if you want to use this feature. Now implementing it is almost as easy. If only someone added this to the official branch…sigh. Expect this to take 10 minutes and work the first time, seriously its that easy…

Modifying Django Admin

First define the special "tag" and "label" class. Technically this could be a tuple of strings…next version. Simply add it to the admin models.

Django-0.95/django/contrib/admin/models.py

Follow that up with a one line change to the view handler for admin change forms. The code below is the whole function for reference but only the line "’form_actions’: opts.admin.form_actions" needs to be added. It just sends the new values from the model to the context.

Django-0.95/django/contrib/admin/views/main.py

def render_change_form(model, manipulator, context, add=False, change=False, form_url=''):
    opts = model._meta
    app_label = opts.app_label
    auto_populated_fields = [f for f in opts.fields if f.prepopulate_from]
    field_sets = opts.admin.get_field_sets(opts)
    original = getattr(manipulator, 'original_object', None)
    bound_field_sets = [field_set.bind(context['form'], original, AdminBoundFieldSet) for field_set in field_sets]
    first_form_field_id = bound_field_sets[0].bound_field_lines[0].bound_fields[0].form_fields[0].get_id();
    ordered_objects = opts.get_ordered_objects()
    inline_related_objects = opts.get_followed_related_objects(manipulator.follow)
    extra_context = {
        'add': add,
        'change': change,
        'has_delete_permission': context['perms'][app_label][opts.get_delete_permission()],
        'has_change_permission': context['perms'][app_label][opts.get_change_permission()],
        'has_file_field': opts.has_field_type(models.FileField),
        'has_absolute_url': hasattr(model, 'get_absolute_url'),
        'auto_populated_fields': auto_populated_fields,
        'bound_field_sets': bound_field_sets,
        'first_form_field_id': first_form_field_id,
        'javascript_imports': get_javascript_imports(opts, auto_populated_fields, field_sets),
        'ordered_objects': ordered_objects,
        'inline_related_objects': inline_related_objects,
        'form_url': form_url,
        'opts': opts,
        'content_type_id': ContentType.objects.get_for_model(model).id,
        'form_actions': opts.admin.form_actions,
    }

context.update(extra_context)
    return render_to_response([
        "admin/%s/%s/change_form.html" % (app_label, opts.object_name.lower()),
        "admin/%s/change_form.html" % app_label,
        "admin/change_form.html"], context_instance=context)

The last change is to add one line to the template to use the new form lists. Modify the change form template, yes you could override it but you already made changes to the admin code. Again the code below is a reference, the only thing to add is the "for loop" line.

Django-0.95/django/contrib/admin/templates/admin/change_form.html

Conclusion

Thats it, now any model can add custom actions to your change forms. in the future the custom class could go away and be replaced by a simple string tuple. Other than that this code is non intrusive, inline with the admin model to date, and super handy when needed. I do wake up with cold sweats imagining that I did something that already exists and is easily handled in a complex and redundant way but so far no one has pinted out a cleaner alternative. Big thanks to the boys at Django for putting together an awesome framework that makes this possible.

Aware Labs Recommends

An interview with Russell Keith-Magee – Django core contributor (USwaretech)
Adding Google Friend Connect is an example of how hard it is to join the 2010 web (Robert Scoble Blog)
Popularizing Django — Or Reusable apps considered harmful. (USwaretech)

Topics: Admin Revisions, Model Revisions | Comments

Hugo

I am using django 0.96, and try to follow your steps. But when I run 'python manage.py runserver' I got an error. The error is:

diagramacao.conteudo: Error when calling the metaclass bases
__init__() got an unexpected keyword argument 'form_actions'

Can you help me?

ChaosKCW

Excellent Article, just what i was looking for! Any sign of inclusion in the trunk ?

Django Aware