Although Media Tree is designed to be agnostic of the module you use to generate image versions and thumbnails, it includes some tags to assist you with generating thumbnails from FileNode objects, since this is one of the most common tasks when working with image files in web applications.
Media Tree’s template tags do not use an imaging toolkit directly, but an abstraction class designed to wrap the actual image manipulation handled by a third-party module (such as easy_thumbnails or sorl.thumbnail, to name two popular choices).
The advantage of wrapping thumbnail generation like this is that Media Tree does not need to depend on a specific image generation library, with the additional benefit that you can just use the abstract template tags in your templates and switch to another MediaBackend at any time.
This module provides a few template tags related to generating thumbnails and image versions. You can use these tags in your templates after loading the tag library as follows:
{% load media_tree_thumbnail %}
Note
Most of the code of this module is an almost identical copy of easy_thumbnails’ template tag, modified to work with FileNode sources and the configured MEDIA_BACKEND. Hence, the thumbnail() tag is compatible to that of easy_thumbnails, but it will work with any thumbnail-generating application if you provide an appropriate MediaBackend class.
Creates a thumbnail of an ImageField or FileNode representing a supported image file.
Basic tag syntax:
{% thumbnail [source] [size] [options] %}
source can be a File object, usually an Image/FileField of a model instance, or a FileNode instance, whose file attribute will be used as the source.
size can either be:
options are a space separated list of options which are used when processing the image to a thumbnail such as sharpen, crop and quality=90.
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 does not return the absolute URL of the thumbnail.
Having access to the ThumbnailFile object is extremely useful, since you should always include the width and height attributes in the output HTML.
Example usage, passing the tag a FileNode instance:
{% thumbnail some_node "100x200" as thumb %}
<img src="{{ thumb.url }} alt="{{ some_node.alt }}"
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.
Returns a pre-configured thumbnail size, or assigns it to a context variable.
Basic tag syntax:
{% thumbnail_size [size_name] [as var_name] %}
The size parameter can be any of the size names configured using the setting MEDIA_TREE_THUMBNAIL_SIZES. If omitted, the default size will be returned.
If the as var_name clause is present, the size will be assigned to the respective context variable instead of being returned.
You can use this template tag in conjunction with thumbnail() in order to use pre-configured thumbnail sizes in your templates.
For example:
{% thumbnail_size "large" as large_size %}
{% thumbnail some_file large_size as large_thumb %}
<img src="{{ large_thumb.url }} width="{{ large_thumb.width }} ... />