Usage¶
The common way easy-thumbnails is used is via the {% thumbnail %}
template
tag or thumbnail_url
filter, which generates images from a model with an
ImageField
. The tag can also be used with media images not tied to a
specific model by passing in the relative path instead.
Custom database fields are also available for simpler access.
The underlying Python code can be used for lower-level generation of thumbnail images.
Overview¶
The primary function of easy-thumbnails is to dynamically create thumbnails based on a source image.
So whenever a thumbnail does not exist or if the source was modified more recently than the existing thumbnail, a new thumbnail is generated (and saved).
Thumbnail aliases can be defined in the
THUMBNAIL_ALIASES
setting, providing
predefined thumbnail options. This also allows for generation of thumbnails
when the source image is uploaded.
Thumbnail options¶
To generate a thumbnail of a source image, you specify options which are used by the image processors to generate the required image.
size
is a required option, and defines the bounds that the generated image
must fit within.
Other options are only provided if the given functionality is required:
quality=<N>
where N is an integer between 1 and 100 specifying output JPEG quality. The default is 85.subsampling=<N>
sets the JPEG color subsampling level where N is:2
is 4:1:1 (both easy-thumbnails and PIL’s default)1
is 4:2:2 (slightly crisper color borders, small increase in size)0
is 4:4:4 (very crisp color borders, ~15% increase in size)
autocrop
removes any unnecessary whitespace from the edges of the source image.bw
converts the image to grayscale.replace_alpha=#colorcode
replaces any transparency layer with a solid color.crop=<smart|scale|W,H>
cuts the edges of the image to match the aspect ratio ofsize
before resizing.- smart means the image is incrementally cropped down to the requested size by removing slices from edges with the least entropy.
- scale means at least one dimension fits within the size dimensions given.
- W,H modifies the cropping origin behavior:
crop="0,0"
will crop from the left and top edges.crop="-10,-0"
will crop from the right edge (with a 10% offset) and the bottom edge.crop=",0"
will keep the default behavior for the x axis (horizontally centering the image) and crop from the top edge.
For a complete and detailed list of options, see the Image Processors reference documentation.
To change a default options level, add it to the
THUMBNAIL_DEFAULT_OPTIONS
setting. Be
aware that this will change the filename for thumbnails, so existing thumbnails
which don’t explicitly specify the new default option will have a new filename
(and therefore be regenerated).
Thumbnail aliases¶
An alias is a specific set of thumbnail options.
Using aliases gives you a single location to define all of your standard thumbnail sizes/options, and avoids repetition of thumbnail options in your code and templates.
An alias may be available project-wide, or set to target a specific app, model or field.
The setting is defined like this:
THUMBNAIL_ALIASES = {
<target>: {
<alias name>: <alias options dictionary>,
...
},
...
}
Use the target ''
for project-wide aliases.
Otherwise, the target should be a string which defines the scope of the
contained aliases:
'sprocket.Widget.image'
would make the aliases available to only the ‘image’ field of a ‘Widget’ model in an app named ‘sprocket’.'sprocket.Widget'
would apply to any field in the ‘Widget’ model.'sprocket'
would target any field in any model in the app.
Pregeneration¶
Some provided signal handlers (along with a new saved_file
signal) allow
for you to have the relevant aliases generated when a file is uploaded.
-
easy_thumbnails.signal_handlers.
generate_aliases
(fieldfile, **kwargs)¶ A saved_file signal handler which generates thumbnails for all field, model, and app specific aliases matching the saved file’s field.
-
easy_thumbnails.signal_handlers.
generate_aliases_global
(fieldfile, **kwargs)¶ A saved_file signal handler which generates thumbnails for all field, model, and app specific aliases matching the saved file’s field, also generating thumbnails for each project-wide alias.
In a module that will be executed when Django loads (such as a models.py
file), register one of these signal handlers. For example:
from easy_thumbnails.signals import saved_file
from easy_thumbnails.signal_handlers import generate_aliases_global
saved_file.connect(generate_aliases_global)
Asynchronous Pregeneration¶
For some use cases, it may not be necessary to have the relevant aliases generated at the exact moment a file is uploaded. As an alternative, the pregeneration task can be queued and executed by a background process.
The following example uses django-celery in conjunction with Celery to achieve this.
models.py:
from django.dispatch import receiver
from easy_thumbnails.signals import saved_file
from myapp import tasks
@receiver(saved_file)
def generate_thumbnails_async(sender, fieldfile, **kwargs):
tasks.generate_thumbnails.delay(
model=sender, pk=fieldfile.instance.pk,
field=fieldfile.field.name)
tasks.py:
from celery import task
from easy_thumbnails.files import generate_all_aliases
@task
def generate_thumbnails(model, pk, field):
instance = model._default_manager.get(pk=pk)
fieldfile = getattr(instance, field)
generate_all_aliases(fieldfile, include_global=True)
This results in a more responsive experience for the user, particularly when dealing with large files and/or remote storage.
Setting aliases for your third-party app¶
If you have a distributable app that uses easy-thumbnails and want to provide an alias, you can modify the aliases at runtime.
For example, put something like this in a module that will execute when Django
initializes (such as models.py
):
from easy_thumbnails.alias import aliases
if not aliases.get('badge'):
aliases.set('badge', {'size': (150, 80), 'crop': True})
Templates¶
To make the easy-thumbnail template library available for use in your template, use:
{% load thumbnail %}
thumbnail_url
filter¶
Return the thumbnail url for a source file using an aliased set of thumbnail options.
If no matching alias is found, returns an empty string.
Example usage:
<img src="{{ person.photo|thumbnail_url:'small' }}" alt="">
{% thumbnail %}
tag¶
If you want to create a thumbnail without providing an alias, use this tag to generate the thumbnail by specifying all of the required options (or with an alias name, to override/supplement the default alias options with dynamic content).
Creates a thumbnail of an ImageField.
Basic tag Syntax:
{% thumbnail [source] [size] [options] %}
source must be a
File
object, usually an Image/FileField of a model instance.size can either be:
- the name of an alias
- the size in the format
[width]x[height]
(for example,{% thumbnail person.photo 100x50 %}
) or - a variable containing a valid size (i.e. either a string in the
[width]x[height]
format or a tuple containing two integers):{% thumbnail person.photo size_var %}
.
options are a space separated list of options which are used when processing the image to a thumbnail such as
sharpen
,crop
andquality=90
.If size is specified as an alias name, options are used to override and/or supplement the options defined in that alias.
The thumbnail tag can also place a
ThumbnailFile
object in the context, providing access to the properties of the thumbnail such as the height and width:{% thumbnail [source] [size] [options] as [variable] %}
When
as [variable]
is used, the tag doesn’t output anything. Instead, use the variable like a standardImageFieldFile
object:{% thumbnail obj.picture 200x200 upscale as thumb %} <img src="{{ thumb.url }}" width="{{ thumb.width }}" height="{{ thumb.height }}" />
Debugging
By default, if there is an error creating the thumbnail or resolving the image variable then the thumbnail tag will just return an empty string (and if there was a context variable to be set then it will also be set to an empty string).
For example, you will not see an error if the thumbnail could not be written to directory because of permissions error. To display those errors rather than failing silently, set
THUMBNAIL_DEBUG = True
in your Django project’s settings module.
For a full list of options, read the Image Processors reference documentation.
Fallback images¶
If you need to support fallback or default images at template level you can use:
{% thumbnail object.image|default:'img/default_image.png' 50x50 %}
Where the image string is relative to your default storage (usually the
MEDIA_ROOT
setting).
Other thumbnailer
filters¶
There are two filters that you can use if you want to get direct access to a thumbnailer in your template. This can be useful when dealing with aliased thumbnails.
Creates a thumbnailer from an object (usually a
FileField
).Example usage:
{% with photo=person.photo|thumbnailer %} {% if photo %} <a href="{{ photo.large.url }}"> {{ photo.square.tag }} </a> {% else %} <img src="{% static 'template/fallback.png' %}" alt="" /> {% endif %} {% endwith %}
If you know what you’re doing, you can also pass the relative name:
{% with photo=storage|thumbnailer:'some/file.jpg' %}...
Creates a thumbnailer from an object (usually a
FileFile
) that won’t generate new thumbnails.This is useful if you are using another process to generate the thumbnails rather than having them generated on the fly if they are missing.
Example usage:
{% with avatar=person.avatar|thumbnailer_passive %} {% with avatar_thumb=avatar.small %} {% if avatar_thumb %} <img src="{{ avatar_thumb.url }}" alt="" /> {% else %} <img src="{% static 'img/default-avatar-small.png' %}" alt="" /> {% endif %} {% endwith %} {% endwith %}
Finally, if you want to have an image inserted inline into the template as a data URI, use this filter:
This filter will return the base64 encoded data URI for a given thumbnail object.
Example usage:
{% thumbnail sample_image 25x25 crop as thumb %} <img src="{{ thumb|data_uri }}">
will for instance be rendered as:
<img src=”data:image/png;base64,iVBORw0KGgo...”>
Models¶
You can use the ThumbnailerField
or ThumbnailerImageField
fields (based
on FileField
and ImageField
, respectively) for easier access to
retrieve (or generate) thumbnail images, use different storages and resize
source images before saving.
-
class
easy_thumbnails.fields.
ThumbnailerField
(*args, **kwargs)¶ A file field which provides easier access for retrieving (and generating) thumbnails.
To use a different file storage for thumbnails, provide the
thumbnail_storage
keyword argument.
-
class
easy_thumbnails.fields.
ThumbnailerImageField
(*args, **kwargs)¶ An image field which provides easier access for retrieving (and generating) thumbnails.
To use a different file storage for thumbnails, provide the
thumbnail_storage
keyword argument.To thumbnail the original source image before saving, provide the
resize_source
keyword argument, passing it a usual thumbnail option dictionary. For example:ThumbnailerImageField( ..., resize_source=dict(size=(100, 100), sharpen=True))
Forms¶
-
class
easy_thumbnails.widgets.
ImageClearableFileInput
(thumbnail_options=None, attrs=None)¶ Use this widget to show a thumbnail of the image next to the image file.
If using the admin and
ThumbnailerField
, you can use this widget automatically with the following code:class MyModelAdmin(admin.ModelAdmin): formfield_overrides = { ThumbnailerField: {'widget': ImageClearableFileInput}, }
-
__init__
(thumbnail_options=None, attrs=None)¶ Set up the thumbnail options for this widget.
Parameters: thumbnail_options – options used to generate the thumbnail. If no size
is given, it’ll be(80, 80)
. If not provided at all, default options will be used from theTHUMBNAIL_WIDGET_OPTIONS
setting.
-
Python¶
Easy thumbnails uses a Django File
-like object called a
Thumbnailer
to generate thumbnail images from the source file which
it references.
get_thumbnailer
¶
The easy way to create a Thumbnailer
instance is to use the following
utility function:
-
easy_thumbnails.files.
get_thumbnailer
(obj, relative_name=None) Get a
Thumbnailer
for a source file.The
obj
argument is usually either one of the following:FieldFile
instance (i.e. a model instance file/image field property).- A string, which will be used as the relative name (the source will be set to the default storage).
Storage
instance - therelative_name
argument must also be provided.
Or it could be:
A file-like instance - the
relative_name
argument must also be provided.In this case, the thumbnailer won’t use or create a cached reference to the thumbnail (i.e. a new thumbnail will be created for every
Thumbnailer.get_thumbnail()
call).
If
obj
is aThumbnailer
instance, it will just be returned. If it’s an object with aneasy_thumbnails_thumbnailer
then the attribute is simply returned under the assumption it is a Thumbnailer instance)
Once you have an instance, you can use the Thumbnailer.get_thumbnail()
method to retrieve a thumbnail, which will (by default) generate it if it
doesn’t exist (or if the source image has been modified since it was created).
For example, assuming an aardvark.jpg
image exists in the default storage:
from easy_thumbnails.files import get_thumbnailer
thumbnailer = get_thumbnailer('animals/aardvark.jpg')
thumbnail_options = {'crop': True}
for size in (50, 100, 250):
thumbnail_options.update({'size': (size, size)})
thumbnailer.get_thumbnail(thumbnail_options)
# or to get a thumbnail by alias
thumbnailer['large']
Non-Django file objects¶
If you need to process a standard file-like object, use get_thumbnailer()
and provide a relative_name
like this:
picture = open('/home/zookeeper/pictures/my_anteater.jpg')
thumbnailer = get_thumbnailer(picture, relative_name='animals/anteater.jpg')
thumb = thumbnailer.get_thumbnail({'size': (100, 100)})
If you don’t even need to save the thumbnail to storage because you are
planning on using it in some more direct way, you can use the
Thumbnailer.generate_thumbnail()
method.
Thumbnails generated in this manor don’t use any cache reference, i.e. every
call to Thumbnailer.get_thumbnail()
will generate a fresh thumbnail
image.