Installation

Installation is easy with pip:

$ pip install django-versatileimagefield

Python Compatibility

  • 2.7.x
  • 3.3.x
  • 3.4.x

Django Compatibility

  • 1.6.x
  • 1.7.x
  • 1.8.x

Dependencies

  • 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 in 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...