django-admin-thumbnails

A Django app to assist in adding thumbnails for your model's image fields to admin list views and forms in a reasonably DRY manner.

Rationale

When working with models that include ImageFields, FileFields or when using ThumbnailerImageField from easy_thumbnails, it can often be desirable to include a thumbnail preview of the field as part of the admin form, fieldset or in list views. Various methods to achieve this exist but all seem to involve a degree of duplication. I've made a few attempts to DRY out such code over the years and this library represents my most recent solution. So, please enjoy!

Compatibility

The widget has been tested on all Python/Django version combinations officially supported by the Django project:

	Django 4.2	5.0	5.1	5.2
Python 3.8	✔
3.9	✔
3.10	✔	✔	✔	✔
3.11	✔	✔	✔	✔
3.12	✔	✔	✔	✔
3.13			✔	✔
3.14				✔

If you need to use django-admin-thumbnails with Django 3, please use a version of the package prior to 1.0.0.

Installation

$ pip install django-admin-thumbnails

Usage

The app adds fields to your ModelAdmin or *Inline class; one for each thumbnail you want to display. These are appended to the class's readonly_fields tuple (unless you specify otherwise) so they will be displayed at the bottom of your admin form, or you can include them by name in your fieldsets or list_display definitions.

django-admin-thumbnails will handle ImageField, FileField (so you can use SVG, for example) and (if easy_thumbnails is installed) ThumbnailerImageField. In the latter case a thumbnail alias will be used, which you can specify in settings.

Basic usage

To create an admin thumbnail field, decorate your ModelAdmin or *Inline class and optionally specify what to do with the newly created field.

Assuming a model like the following:

class Person(models.Model):
    name = models.CharField('Name', max_length=100)
    image = models.ImageField('Image')
    # ...

In the simplest use-case, to add a thumbnail field to the bottom of the admin form, simply decorate the ModelAdmin or *Inline class (the order of decorators is important), supplying the name of the field from which the thumbnail will be taken:

import admin_thumbnails

@admin.register(models.Person)
@admin_thumbnails.thumbnail('image')
class PersonAdmin(admin.ModelAdmin):
    pass

This will add a field called image_thumbnail (FOO_thumbnail where FOO is the origin field's name) to your ModelAdmin or *Inline definition. To override the title given to the new field, pass a second string argument to the decorator:

@admin_thumbnails.thumbnail('image', 'Thumbnail')

To add the thumbnail to the columns shown in the model's list view, add the new field name to list_display:

@admin.register(models.Person)
@admin_thumbnails.thumbnail('image')
class PersonAdmin(admin.ModelAdmin):
    list_display = ('name', 'image_thumbnail')

Or include it in your fieldsets similarly:

@admin.register(models.Person)
@admin_thumbnails.thumbnail('image')
class PersonAdmin(admin.ModelAdmin):
    fieldsets = (
        (None, {
            'fields': ('name', 'image_thumbnail'),
        }),
    )

Using thumbnails in the list view only

By default the new field will be appended to the readonly_fields tuple – if this is undesirable (e.g. if you want to include the thumbnail in the list view but not in the default form fields), pass append=False to the decorator:

@admin.register(models.Person)
@admin_thumbnails.thumbnail('image', append=False)
class PersonAdmin(admin.ModelAdmin):
    list_display = ('name', 'image_thumbnail')

This isn't necessary if you're using fieldsets, as by doing so you will control the inclusion (or omission) and position of the thumbnail field.

Using a property on the model as the thumbnail source

As of version 0.2.7, the name passed to the thumbnail decorator can refer to a property on the model rather than a field. For example:

class Person(models.Model):
    # ...
    @property
    def primary_image(self):
        first_image = self.images.first()
        if first_image:
            return first_image.image
        return None

Provided the specified property returns an instance of a FieldFile (i.e. a file stored in a field that is an instance of Django's ImageField, FileField, or easy_thumbnails' ThumbnailerImageField), this will work as normal.

This also works with Django's cached_property decorator.

Adding a background to displayed thumbnails

If your field contains images that are designed to be shown on a dark background, you can supply background=True to the decorator to add one to the thumbnail (via CSS) when displayed:

@admin_thumbnails.thumbnail('image', background=True)

If you're using easy_thumbnails and want to override the alias used to generate your thumbnail on a per-field basis (as opposed to using the ADMIN_THUMBNAIL_THUMBNAIL_ALIAS setting; see below), you can use the alias argument to the decorator:

@admin_thumbnails.thumbnail('image', alias='admin_thumbnail_alternative')

Configuration

ADMIN_THUMBNAIL_DEFAULT_LABEL

Default: 'Preview'

Setting this overrides the default column name / title used by thumbnails.

ADMIN_THUMBNAIL_FIELD_SUFFIX

Default: '_thumbnail'

Setting this overrides the suffix given to newly created thumbnail fields. Change if you have collision issues with other field names you want to use. Don't forget to update list_display and/or fieldsets in your ModelAdmin as necessary.

ADMIN_THUMBNAIL_THUMBNAIL_ALIAS

Default: 'admin_thumbnail'

If easy_thumbnails is installed and available, any model field using ThumbnailerImageField will be resized using a thumbnail alias called admin_thumbnail if it's defined. You can either define this alias in your settings (more info from the easy_thumbnails documentation here) or supply a different alias name as the value of this setting.

ADMIN_THUMBNAIL_STYLE

Default: {'display': 'block', 'width': '100px', 'height': 'auto'}

A dictionary of CSS property/value pairs that will be added to the style attribute of any thumbnail image when output in the admin. Override to supply your own styles.

ADMIN_THUMBNAIL_BACKGROUND_STYLE

Default: {'background': '#000'}

A dictionary of CSS property/value pairs added when the background=True option is used (see Usage above). Override to supply your own styles. Note that these styles are used in addition to any defined in ADMIN_THUMBNAIL_STYLE.

Development

If working locally on the package you can install the development tools via pip:

$ pip install -e .[dev]

Run the bundled Django example project:

$ cd example_project
$ python manage.py runserver 0.0.0.0:8000
$ open http://localhost:8000/admin/

Log in with the username admin and the password admin.

Navigate to the example Book model in the Bookshop app to see the widget in action.

Run the basic test suite across environments using tox:

$ tox run

Issues, suggestions, contributions

...are welcome on GitHub. Thanks for your interest in django-admin-thumbnails!