# 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 `ImageField`s, `FileField`s 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
I've not exhaustively tested all the below combinations, however I believe this table to be accurate.
| | Django 1.10 | 1.11 | 2.0 | 2.1 | 2.2 | 3.0 | 3.1 | 3.2 | 4.0 | 4.1 | 4.2 |
| -------------: | :---------: | :--: | :-: | :-: | :-: | :-: | :-: | :-: | :-: | :-: | :-: |
| **Python** 2.7 | ✔ | ✔ | | | | | | | | | |
| 3.6 | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | | | |
| >= 3.8 | | | | | | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
## 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:
```python
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:
```python
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:
```python
@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`:
```python
@admin.register(models.Person)
@admin_thumbnails.thumbnail('image')
class PersonAdmin(admin.ModelAdmin):
list_display = ('name', 'image_thumbnail')
```
Or include it in your `fieldsets` similarly:
```python
@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:
```python
@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:
```python
class Person(models.Model):
# ...
@property
def primary_image(self):
if self.images.count():
return self.images.first().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`](https://docs.djangoproject.com/en/dev/ref/utils/#django.utils.functional.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:
```python
@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:
```python
@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](https://easy-thumbnails.readthedocs.io/en/stable/usage/#thumbnail-aliases)) 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 installation
If working locally on the package you can install the development tools via `pip`:
```shell
$ pip install -e .[dev]
```
To lint with `flake8`:
```shell
$ flake8
```
## Issues, suggestions, contributions
...are welcome on GitHub. Thanks for your interest in `django-admin-thumbnails`!
Raw data
{
"_id": null,
"home_page": "http://github.com/BigglesZX/django-admin-thumbnails",
"name": "django-admin-thumbnails",
"maintainer": "James Tiplady",
"docs_url": null,
"requires_python": ">=2.6,<4",
"maintainer_email": "",
"keywords": "django",
"author": "James Tiplady",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/0c/ab/54c6ab6a5e6554a2efec7b5a9749a8771155a2614d1f07c692a0b43f96ae/django-admin-thumbnails-0.2.8.tar.gz",
"platform": "OS Independent",
"description": "# django-admin-thumbnails\n\nA Django app to assist in adding thumbnails for your model's image fields to admin list views and forms in a reasonably DRY manner.\n\n## Rationale\n\nWhen working with models that include `ImageField`s, `FileField`s 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!\n\n## Compatibility\n\nI've not exhaustively tested all the below combinations, however I believe this table to be accurate.\n\n| | Django 1.10 | 1.11 | 2.0 | 2.1 | 2.2 | 3.0 | 3.1 | 3.2 | 4.0 | 4.1 | 4.2 |\n| -------------: | :---------: | :--: | :-: | :-: | :-: | :-: | :-: | :-: | :-: | :-: | :-: |\n| **Python** 2.7 | \u2714 | \u2714 | | | | | | | | | |\n| 3.6 | \u2714 | \u2714 | \u2714 | \u2714 | \u2714 | \u2714 | \u2714 | \u2714 | | | |\n| >= 3.8 | | | | | | \u2714 | \u2714 | \u2714 | \u2714 | \u2714 | \u2714 |\n\n## Installation\n\n```\n$ pip install django-admin-thumbnails\n```\n\n## Usage\n\nThe 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.\n\n`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.\n\n### Basic usage\n\nTo create an admin thumbnail field, decorate your `ModelAdmin` or `*Inline` class and optionally specify what to do with the newly created field.\n\nAssuming a model like the following:\n\n```python\nclass Person(models.Model):\n name = models.CharField('Name', max_length=100)\n image = models.ImageField('Image')\n # ...\n```\n\nIn 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:\n\n```python\nimport admin_thumbnails\n\n@admin.register(models.Person)\n@admin_thumbnails.thumbnail('image')\nclass PersonAdmin(admin.ModelAdmin):\n pass\n```\n\nThis 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:\n\n```python\n@admin_thumbnails.thumbnail('image', 'Thumbnail')\n```\n\nTo add the thumbnail to the columns shown in the model's list view, add the new field name to `list_display`:\n\n```python\n@admin.register(models.Person)\n@admin_thumbnails.thumbnail('image')\nclass PersonAdmin(admin.ModelAdmin):\n list_display = ('name', 'image_thumbnail')\n```\n\nOr include it in your `fieldsets` similarly:\n\n```python\n@admin.register(models.Person)\n@admin_thumbnails.thumbnail('image')\nclass PersonAdmin(admin.ModelAdmin):\n fieldsets = (\n (None, {\n 'fields': ('name', 'image_thumbnail'),\n }),\n )\n```\n\n### Using thumbnails in the list view only\n\nBy default the new field will be appended to the `readonly_fields` tuple \u2013 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:\n\n```python\n@admin.register(models.Person)\n@admin_thumbnails.thumbnail('image', append=False)\nclass PersonAdmin(admin.ModelAdmin):\n list_display = ('name', 'image_thumbnail')\n```\n\nThis 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.\n\n### Using a property on the model as the thumbnail source\n\nAs 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:\n\n```python\nclass Person(models.Model):\n # ...\n @property\n def primary_image(self):\n if self.images.count():\n return self.images.first().image\n return None\n```\n\nProvided 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.\n\nThis also works with Django's [`cached_property`](https://docs.djangoproject.com/en/dev/ref/utils/#django.utils.functional.cached_property) decorator.\n\n### Adding a background to displayed thumbnails\n\nIf 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:\n\n```python\n@admin_thumbnails.thumbnail('image', background=True)\n```\n\nIf 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:\n\n```python\n@admin_thumbnails.thumbnail('image', alias='admin_thumbnail_alternative')\n```\n\n## Configuration\n\n### `ADMIN_THUMBNAIL_DEFAULT_LABEL`\n\n**Default:** `'Preview'`\n\nSetting this overrides the default column name / title used by thumbnails.\n\n### `ADMIN_THUMBNAIL_FIELD_SUFFIX`\n\n**Default:** `'_thumbnail'`\n\nSetting 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.\n\n### `ADMIN_THUMBNAIL_THUMBNAIL_ALIAS`\n\n**Default:** `'admin_thumbnail'`\n\nIf `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](https://easy-thumbnails.readthedocs.io/en/stable/usage/#thumbnail-aliases)) or supply a different alias name as the value of this setting.\n\n### `ADMIN_THUMBNAIL_STYLE`\n\n**Default:** `{'display': 'block', 'width': '100px', 'height': 'auto'}`\n\nA 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.\n\n### `ADMIN_THUMBNAIL_BACKGROUND_STYLE`\n\n**Default:** `{'background': '#000'}`\n\nA 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`.\n\n## Development installation\n\nIf working locally on the package you can install the development tools via `pip`:\n\n```shell\n$ pip install -e .[dev]\n```\n\nTo lint with `flake8`:\n\n```shell\n$ flake8\n```\n\n## Issues, suggestions, contributions\n\n...are welcome on GitHub. Thanks for your interest in `django-admin-thumbnails`!",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Django app for DRY thumbnails in admin list views and forms.",
"version": "0.2.8",
"project_urls": {
"Homepage": "http://github.com/BigglesZX/django-admin-thumbnails"
},
"split_keywords": [
"django"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0cab54c6ab6a5e6554a2efec7b5a9749a8771155a2614d1f07c692a0b43f96ae",
"md5": "78bbc0e47d883d773cbab3e02c0ef06c",
"sha256": "97f25fade58ec137d68ed64d55d4898681cd65d2f5caf4c6ce908ea993b175e6"
},
"downloads": -1,
"filename": "django-admin-thumbnails-0.2.8.tar.gz",
"has_sig": false,
"md5_digest": "78bbc0e47d883d773cbab3e02c0ef06c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=2.6,<4",
"size": 6974,
"upload_time": "2023-06-01T14:50:29",
"upload_time_iso_8601": "2023-06-01T14:50:29.118986Z",
"url": "https://files.pythonhosted.org/packages/0c/ab/54c6ab6a5e6554a2efec7b5a9749a8771155a2614d1f07c692a0b43f96ae/django-admin-thumbnails-0.2.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-01 14:50:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "BigglesZX",
"github_project": "django-admin-thumbnails",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "django-admin-thumbnails"
}
JSON
