Usage
This section contains information, including examples, about how to use
django-thumbnail-works in your existing Django projects or applications.
The EnhancedImageField
-
class thumbnail_works.fields.EnhancedImageField(process_source=None, thumbnails={}, **kwargs)
This model field is an enhanced version of Django’s ImageField.
django-thumbnail-works provides an enhanced version of the default Django’s
ImageField, which supports:
- Processing the original image before it is saved on the remote server.
- Generating thumbnails of the source image and a mechanism of accessing
the thumbnails as attributes of the source image.
The EnhancedImageField derives from the default ImageField and thus
all attributes and methods of the default ImageField are inherited.
In addition to the default arguments, the EnhancedImageField also
supports the following:
- process_source
- A dictionary of image processing options. The same options, that can
be used for the thumbnail generation, can also be set in this attribute.
If this is set, the original image will be processed using the provided
options before it is saved on the remote server. Contrariwise, if this
attribute is not set or set to None, the uploaded image is saved in
its original form, without any further processing. It should be noted that
setting this attribute to an empty dictionary still causes the source
image to be processed using default image processing options. This
practically means that the source image will be saved in the format
specified by the THUMBNAILS_FORMAT setting without any resizing or
filtering taking place.
- thumbnails
A dictionary of thumbnail definitions. The format of each thumbnail
definition is:
<thumbnail_identifier> : <image_processing_options>
- thumbnail_identifier
- Is a string that uniquely identifies the thumbnail. It is required
that all thumbnails use a unique identifier. This identifier is used
in the thumbnail access mechanism and is also used in the
generated filename of the thumbnail image file.
- image_processing_options
This is a dictionary of options that will be used during the thumbnail
generation. This dictionary must be present on every thumbnail
definition. Any of the following supported options may be used:
- size
- A string of the format WIDTHxHEIGHT which represents the
size of the generated thumbnail.
- sharpen
- Boolean option. If set, the ImageFilter.SHARPEN filter will
be applied to the thumbnail.
- detail
- Boolean option. If set, the ImageFilter.DETAIL filter will
be applied to the thumbnail.
- upscale
- Boolean option. By default, image resizing occurs only if
any of the source image dimensions is bigger than the dimension
indicated by the size option. If the upscale option is
set to True, resizing occurs even if the generated thumbnail
is bigger than the source image.
- format
- This is the format in which the thumbnail should be saved.
Valid values are those supported by the Python Imaging Library
(PIL). If it is not set, then the default format specified by
the THUMBNAILS_FORMAT setting will be used. In case the
format is set to JPEG, the value of the THUMBNAILS_QUALITY
is used as the quality when the image is saved.
The following code snippet illustrates how to use the EnhancedImageField:
from django.db import models
from thumbnail_works.fields import EnhancedImageField
class MyModel(models.Model):
photo = EnhancedImageField(
upload_to = 'attachments/images',
process_source = dict(
size='512x384', sharpen=True, upscale=True, format='JPEG'),
thumbnails = {
'avatar': dict(size='80x60'),
'medium': dict(size='256x192', detail=True),
}
)
Accessing thumbnails
-
class thumbnail_works.fields.EnhancedImageFieldFile(instance, field, name)
Each of the thumbnails that have been specified in the thumbnails
dictionary are eventually set as attributes of the source image object.
Each thumbnail’s identifier is used as the name of the attribute.
For example, the avatar thumbnail of a photo field, would be
accessed as:
Thumbnails inherit all the attributes of Django’s ImageFieldFile
as described in the file objects documentation.
For instance, you can do something like the following in your templates:
<img src="{{ photo.avatar.url }}"
width="{{ photo.avatar.width }}"
height="{{ photo.avatar.height }}"
alt='{{ user.name }}' />
Is that it?
Indeed, that’s pretty much all you can do with django-thumbnail-works.