django-adminlink 0.3.0

A Django package to add links for ForeignKey fields in the admin

Django-adminlink

The Django admin allows to list rows in an easy way. Some feature that seems to be "missing" is to jump in an efficient way to the detail view of a related object. For example if a model A has a ForeignKey to B, then the ModelAdmin of A can show the __str__ of B, but without a link.

Django's admin actions are also very useful, but what seems to be missing is an easy way to just run the action on a single row without too much "hassle".

This package provides a mixin to effectively add such links.

Installation

You can install the package with:

pip install django-adminlink

You do not need to add 'django_adminlink' to the INSTALLED_APPS settings unless you use the SingleItemActionMixin or a derived product from it. In that case, you need to make use of the static/js/single_admin_action.js file that ships with it. Then the INSTALLED_APPS looks like:

# settings.py

# …

INSTALLED_APPS = [
    # …,
    'django_adminlink'
]

Usage

Once the package is installed, we can work with the mixins provided by the package.

Adding links to ForeignKey fields

you can use the LinkFieldAdminMixin mixin in the admins where you want ForeignKeys and OneToOneFields to be linked to the corresponding admin detail view of that object:

from django.contrib import admin
from django_adminlink.admin import LinkFieldAdminMixin


@admin.register(Movie)
class MovieAdmin(LinkFieldAdminMixin, admin.ModelAdmin):
    list_display = ['__str__', 'genre']

If genre is a ForeignKey to a Genre model for example, and Genre has its own ModelAdmin, it will automatically convert genre into a column that adds a link to the admin detail view of the corresponding genre.

Single row actions

The package also provides a SingleItemActionMixin, this enables to add a column at the right end of the admin that contains (one or more) buttons. These buttons then run a Django admin action on a single record.

One can specify which actions to run by listing these, for example:

from django.contrib import admin
from django_adminlink.admin import SingleItemActionMixin

@admin.register(Movie)
class MovieAdmin(SingleItemActionMixin, admin.ModelAdmin):
    action_buttons = {'delete': 'delete_selected'}

One can work with a dictionary that has as key the "label" of the button, and as value the name (key) of the action to work with. This will add a button with the label "delete" as last column. When clicked, that row, and only that row is then removed.

The package does not perform the action itself: it works with a small amount of JavaScript that just disables all checkboxes, enables only the checkbox of the selected row, and finally submits the action form, letting Django handle the rest of the logic.

If the label(s) and action(s) are the same, one can also work with a list of the names of the actions, like:

from django.contrib import admin
from django_adminlink.admin import SingleItemActionMixin

@admin.register(Movie)
class MovieAdmin(SingleItemActionMixin, admin.ModelAdmin):
    action_buttons = ['delete_selected']

Grouping actions

The list of actions is "flat". We can add item groups, just like in other Django ChoiceFields. For this, we introduced the GroupedActionAdminMixin.

This mixin looks at the actions. We also defined a @grouped_action decorator, which does approximately the same as the @admin.action decorator, except with an extra parameter action_group=….

We can register actions like:

from django.contrib import admin
from django_adminlink.admin import GroupedActionAdminMixin, grouped_action

@admin.register(Movie)
class MovieAdmin(GroupedActionAdminMixin, admin.ModelAdmin):
    action_buttons = ['star', 'unstar', 'clear_comments']
    
    @grouped_action(description='star item', action_group='stars')
    def star(self, request, queryset):
      # …
    
    @grouped_action(description='unstar item', action_group='stars')
    def unstar(self, request, queryset):
      # …
    
    @grouped_action(description='clear comments', action_group='comments')
    def clear_comments(self, request, queryset):
      # …

The order of the groups is determined by the order of the individual actions: the first action for that group for each group determines how the groups are listed.