Sorl-thumbnail is a very useful package to deal with images in the Django template. It is very easy to implement. Resizing and cropping images become simple with inbuilt tags provided by sorl-thumbnail.

Installation and setup:

To install sorl-thumbnail

Pip install Sorl-thumbnail

To setup, add sorl.thumbnail to INSTALLED_APPS in settings.

Then create the migrations with

python manage.py makemigrations thumbnail

and migrate with

python manage.py migrate thumbnail

Now sorl-thumbnail is ready to use in your project.

To use sorl-thumbnail we should install python image library

pip install Pillow

Key Value Store:

sorl-thumbnail needs key value store to maintain the keys and values of the thumbnails generated from the images and its storage. Storage can be our own server or it can be any cloud storage services like Amazon S3, Microsoft azure etc. To store the images in these cloud storage services, django-storages package is very useful.

Template tags and filters for sorl-thumbnail:

sorl-thumbnail has one tag and three filters to use in templates. To use these filters and tag we should load them first with

{% load thumbnail %}

thumbnail tag:

When you use this tag sorl-thumbnail searches the thumbnail in Key Value store. If thumbnail found it returns the serialized thumbnail information, if not found it will generate the thumbnail and stores the information in Key     Value store.

{% thumbnail item.image '200x100' as im %
  <img src='{{ im.url }}'>

{% endthumbnail %}

We need to provide image field and width, height in pixels to thumbnail to display the image in given width and height. It can preserve aspect ratio.

thumbnail also provide some options like crop, format, quality, padding, padding_color.. etc to customize the image

For example

{% thumbnail item.image '100x100' padding=True as im %}

Now the image will get padding at the top and bottom.

Filters:

1. is_portrait:

This filter is used to check whether the image is in portrait format (return True if the image height is larger than width)

{{ item.image|is_portrait }}

2. margin:

This filter is used to calculate the margin against padding box.

{% thumbnail item.image '100x100' as im %}
  <img src='{{ im.url }}' style='margin:{{ im|margin:"100x100" }}'>
{% endthumbnail %}

here the image gets padding vertically in a 100x100 box.

3. resolution:

This filter is used to get the alternative resolution versions of the thumbnail. The resolution you provided should be one of the THUMBNAIL_ALTERNATIVE_RESOLUTIONS in settings.

<img src="{{ item.image.url|resolution:'2x' }}">
<img src="{{ item.image.url|resolution:'1.5x' }}">

To use above filters you should have THUMBNAIL_ALTERNATIVE_RESOLUTIONS = [1.5, 2] in your settings.

Useful Thumbnail management commands:

thumbnail cleanup:

python manage.py thumbnail cleanup

It will remove thumbnails for unknown and nonexisting images from the Key Value store.

thumbnail clear:

python manage.py thumbnail clear

It will empty the Key Value store of keys starts with settings.THUMBNAIL_KEY_PREFIX. It doesn't delete any files.