Examples

Template examples

All of the examples assume that you first load the thumbnail template tag in your template:

{% load thumbnail %}

Simple:

{% thumbnail item.image "100x100" crop="center" as im %}
    <img src="{{ im.url }}" width="{{ im.width }}" height="{{ im.height }}">
{% endthumbnail %}

Crop using margin filter, x, y aliases:

{% thumbnail item.image "100x700" as im %}
    <img style="margin:{{ im|margin:"100x700" }}" src="{{ im.url }}" width="{{ im.x }}" height="{{ im.y }}">
{% endthumbnail %}

Using external images and advanced cropping:

{% thumbnail "http://www.aino.se/media/i/logo.png" "40x40" crop="80% top" as im %}
    <img src="{{ im.url }}">
{% endthumbnail %}

Using the empty feature, the empty section is rendered when the source is resolved to an empty value or an invalid image source, you can think of it as rendering when the thumbnail becomes undefined:

{% thumbnail item.image my_size_string crop="left" as im %}
    <img src="{{ im.url }}">
{% empty %}
    <p>No image</p>
{% endthumbnail %}

Nesting tags and setting size (geometry) for width only:

{% thumbnail item.image "1000" as big %}
    {% thumbnail item.image "50x50" crop="center" as small %}
        <a href="{{ big.url}}" title="look ma!"><img src="{{ small.url }}"></a>
    {% endthumbnail %}
{% endthumbnail %}

Setting geometry for height only:

{% thumbnail item.image "x300" as im %}
    <img src="{{ im.url }}">
{% endthumbnail %}

Setting format and using the is_portrait filter:

{% if item.image|is_portrait %}
    <div class="portrait">
    {% thumbnail item.image "100" crop="10px 10px" format="PNG" as im %}
        <img src="{{ im.url }}">
    {% endthumbnail %}
    </div>
{% else %}
    <div class="landscape">
    {% thumbnail item.image "50" crop="bottom" format="PNG" as im %}
        <img src="{{ im.url }}">
    {% endthumbnail %}
    </div>
    <div>
        <p>Undefined behaviour</p>
    </div>
{% endif %}

Model examples

Using the ImageField that automatically deletes references to itself in the key value store and its thumbnail references and the thumbnail files when deleted:

from django.db import models
from sorl.thumbnail import ImageField

class Item(models.Model):
    image = ImageField()

Note

You do not need to use the sorl.thumbnail.ImageField to use sorl.thumbnail. The standard django.db.models.ImageField is fine except that it does not know how to delete itself from the Key Value Store or its thumbnails if you delete it. Also using the sorl.thumbnail.ImageField lets you plugin the nice admin addition explained in the next section.

Another example on how to use sorl.thumbnail.ImageField in your existing project with only small code changes:

# util/models.py
from django.db.models import *
from sorl.thumbnail import ImageField

# myapp/models.py
from util import models

class MyModel(models.Model):
    logo = models.ImageField(upload_to='/dev/null')

Admin examples

Recommended usage using sorl.thumbnail.admin.AdminImageMixin:

# myapp/admin.py
from django.contrib import admin
from myapp.models import MyModel
from sorl.thumbnail.admin import AdminImageMixin

class MyModelAdmin(AdminImageMixin, admin.ModelAdmin):
    pass

And the same thing For inlines:

# myapp/admin.py
from django.contrib import admin
from myapp.models import MyModel, MyInlineModel
from sorl.thumbnail.admin import AdminImageMixin

class MyInlineModelAdmin(AdminImageMixin, admin.TabularInline):
    model = MyInlineModel

class MyModelAdmin(admin.ModelAdmin):
    inlines = [MyInlineModelAdmin]

Easy to plugin solution example with little code to change:

# util/admin.py
from django.contrib.admin import *
from sorl.thumbnail.admin import AdminImageMixin

class ModelAdmin(AdminImageMixin, ModelAdmin):
    pass

class TabularInline(AdminImageMixin, TabularInline):
    pass

class StackedInline(AdminImageMixin, StackedInline):
    pass

# myapp/admin.py
from util import admin
from myapp.models import MyModel

class MyModelAdmin(admin.ModelAdmin):
    pass

Low level API examples

How to get make a thumbnail in you python code:

from sorl.thumbnail import get_thumbnail

im = get_thumbnail(my_file, '100x100', crop='center', quality=99)

How to delete a file, its thumbnails as well as references in the Key Value Store:

from sorl.thumbnail import delete

delete(my_file)