Installation¶
Installation is easy with pip:
$ pip install django-versatileimagefield
Python Compatibility¶
- 2.7.x
- 3.3.x
- 3.4.x
Dependencies¶
- django>=1.6.x
- Pillow >= 2.4.x
django-versatileimagefield depends on the excellent Pillow fork of PIL. If you already have PIL installed, it is recommended you uninstall it prior to installing django-versatileimagefield:
$ pip uninstall PIL
$ pip install django-versatileimagefield
Note
django-versatileimagefield will not install django.
Settings¶
After installation completes, add 'versatileimagefield' to INSTALLED_APPS:
INSTALLED_APPS = (
# All your other apps here
'versatileimagefield',
)
VERSATILEIMAGEFIELD_SETTINGS¶
A dictionary that allows you to fine-tune how django-versatileimagefield works:
VERSATILEIMAGEFIELD_SETTINGS = {
# The amount of time, in seconds, that references to created images
# should be stored in the cache. Defaults to `2592000` (30 days)
'cache_length': 2592000,
# The name of the cache you'd like `django-versatileimagefield` to use.
# Defaults to 'versatileimagefield_cache'. If no cache exists with the name
# provided, the 'default' cache will be used instead.
'cache_name': 'versatileimagefield_cache',
# The save quality of modified JPEG images. More info here:
# http://pillow.readthedocs.org/en/latest/handbook/image-file-formats.html#jpeg
# Defaults to 70
'jpeg_resize_quality': 70,
# The name of the top-level folder within storage classes to save all
# sized images. Defaults to '__sized__'
'sized_directory_name': '__sized__',
# The name of the directory to save all filtered images within.
# Defaults to '__filtered__':
'filtered_directory_name': '__filtered__',
# The name of the directory to save placeholder images within.
# Defaults to '__placeholder__':
'placeholder_directory_name': '__placeholder__',
# Whether or not to create new images on-the-fly. Set this to `False` for
# speedy performance but don't forget to 'pre-warm' to ensure they're
# created and available at the appropriate URL.
'create_images_on_demand': True
}
VERSATILEIMAGEFIELD_USE_PLACEHOLDIT¶
A boolean that signifies whether optional (blank=True) VersatileImageField fields that do not specify a placeholder image should return placehold.it URLs.
VERSATILEIMAGEFIELD_RENDITION_KEY_SETS¶
A dictionary used to specify ‘Rendition Key Sets’ that are used for both serialization or as a way to ‘warm’ image files so they don’t need to be created on demand (i.e. when settings.VERSATILEIMAGEFIELD_SETTINGS['create_images_on_demand'] is set to False) which will greatly improve the overall performance of your app. Here’s an example:
VERSATILEIMAGEFIELD_RENDITION_KEY_SETS = {
'image_gallery': [
('gallery_large', 'crop__800x450'),
('gallery_square_small', 'crop__50x50')
],
'primary_image_detail': [
('hero', 'crop__600x283'),
('social', 'thumbnail__800x800')
],
'primary_image_list': [
('list', 'crop__400x225'),
],
'headshot': [
('headshot_small', 'crop__150x175'),
]
}
Each key in VERSATILEIMAGEFIELD_RENDITION_KEY_SETS signifies a ‘Rendition Key Set’, a list comprised of 2-tuples wherein the first position is a serialization-friendly name of an image rendition and the second position is a ‘Rendition Key’ (which dictates how the original image should be modified).
Writing Rendition Keys¶
Rendition Keys are intuitive and easy to write, simply swap out double-underscores for the dot-notated paths you’d use in the shell or in templates. Examples:
Intended image | As ‘Rendition Key’ | In the shell | In templates |
---|---|---|---|
400px by 400px Crop | 'crop__400x400' | instance.image_field.crop['400x400'].url | {{ instance.image_field.crop.400x400 }} |
100px by 100px Thumbnail | 'thumbnail__100x100' | instance.image_field.thumbnail['100x100'].url | {{ instance.image_field.thumbnail.100x100 }} |
Inverted Image (Full Size) | 'filters__invert' | instance.image_field.filters.invert.url | {{ instance.image_field.filters.invert }} |
Inverted Image, 50px by 50px crop | 'filters__invert__crop__50x50' | instance.image_field.filters.invert.crop['50x50'].url | {{ instance.image_field.filters.invert.crop.50x50 }} |
Using Rendition Key Sets¶
Rendition Key sets are useful! Read up on how they can help you...
- ... serializing VersatileImageField instances within Django REST Framework.
- ... ‘warm’ images to improve performance.