1******** 2Examples 3******** 4 5Template examples 6================= 7 8.. highlight:: html+django 9 10All of the examples assume that you first load the ``thumbnail`` template tag in 11your template:: 12 13 {% load thumbnail %} 14 15Simple:: 16 17 {% thumbnail item.image "100x100" crop="center" as im %} 18 <img src="{{ im.url }}" width="{{ im.width }}" height="{{ im.height }}"> 19 {% endthumbnail %} 20 21 22Crop using margin filter, x, y aliases:: 23 24 {% thumbnail item.image "100x700" as im %} 25 <img style="margin:{{ im|margin:"100x700" }}" src="{{ im.url }}" width="{{ im.x }}" height="{{ im.y }}"> 26 {% endthumbnail %} 27 28Using external images and advanced cropping:: 29 30 {% thumbnail "http://www.aino.se/media/i/logo.png" "40x40" crop="80% top" as im %} 31 <img src="{{ im.url }}"> 32 {% endthumbnail %} 33 34Using the empty feature, the empty section is rendered when the source is 35resolved to an empty value or an invalid image source, you can think of it as 36rendering when the thumbnail becomes undefined:: 37 38 {% thumbnail item.image my_size_string crop="left" as im %} 39 <img src="{{ im.url }}"> 40 {% empty %} 41 <p>No image</p> 42 {% endthumbnail %} 43 44Nesting tags and setting size (geometry) for width only:: 45 46 {% thumbnail item.image "1000" as big %} 47 {% thumbnail item.image "50x50" crop="center" as small %} 48 <a href="{{ big.url}}" title="look ma!"><img src="{{ small.url }}"></a> 49 {% endthumbnail %} 50 {% endthumbnail %} 51 52Setting geometry for height only:: 53 54 {% thumbnail item.image "x300" as im %} 55 <img src="{{ im.url }}"> 56 {% endthumbnail %} 57 58Setting format and using the is_portrait filter:: 59 60 {% if item.image|is_portrait %} 61 <div class="portrait"> 62 {% thumbnail item.image "100" crop="10px 10px" format="PNG" as im %} 63 <img src="{{ im.url }}"> 64 {% endthumbnail %} 65 </div> 66 {% else %} 67 <div class="landscape"> 68 {% thumbnail item.image "50" crop="bottom" format="PNG" as im %} 69 <img src="{{ im.url }}"> 70 {% endthumbnail %} 71 </div> 72 <div> 73 <p>Undefined behaviour</p> 74 </div> 75 {% endif %} 76 77Using HTML filter:: 78 79 {{ text|html_thumbnails }} 80 81Using markdown filter:: 82 83 {{ text|markdown_thumbnails }} 84 85.. highlight:: python 86 87Model examples 88============== 89Using the ImageField that automatically deletes references to itself in the key 90value store and its thumbnail references when deleted:: 91 92 from django.db import models 93 from sorl.thumbnail import ImageField 94 95 class Item(models.Model): 96 image = ImageField(upload_to='whatever') 97 98 99.. note:: You do not need to use the ``sorl.thumbnail.ImageField`` to use 100 ``sorl.thumbnail``. The standard ``django.db.models.ImageField`` is fine 101 except that using the ``sorl.thumbnail.ImageField`` lets you plugin the 102 nice admin addition explained in the next section. 103 104 105Another example on how to use ``sorl.thumbnail.ImageField`` in your existing 106project with only small code changes:: 107 108 # util/models.py 109 from django.db.models import * 110 from sorl.thumbnail import ImageField 111 112 # myapp/models.py 113 from util import models 114 115 class MyModel(models.Model): 116 logo = ImageField(upload_to='/dev/null') 117 118 119Admin examples 120============== 121Recommended usage using ``sorl.thumbnail.admin.AdminImageMixin`` (note that this requires use of ``sorl.thumbnail.ImageField`` in your models as explained above):: 122 123 # myapp/admin.py 124 from django.contrib import admin 125 from myapp.models import MyModel 126 from sorl.thumbnail.admin import AdminImageMixin 127 128 class MyModelAdmin(AdminImageMixin, admin.ModelAdmin): 129 pass 130 131And the same thing For inlines:: 132 133 # myapp/admin.py 134 from django.contrib import admin 135 from myapp.models import MyModel, MyInlineModel 136 from sorl.thumbnail.admin import AdminImageMixin 137 138 class MyInlineModelAdmin(AdminImageMixin, admin.TabularInline): 139 model = MyInlineModel 140 141 class MyModelAdmin(admin.ModelAdmin): 142 inlines = [MyInlineModelAdmin] 143 144Easy to plugin solution example with little code to change:: 145 146 # util/admin.py 147 from django.contrib.admin import * 148 from sorl.thumbnail.admin import AdminImageMixin 149 150 class ModelAdmin(AdminImageMixin, ModelAdmin): 151 pass 152 153 class TabularInline(AdminImageMixin, TabularInline): 154 pass 155 156 class StackedInline(AdminImageMixin, StackedInline): 157 pass 158 159 # myapp/admin.py 160 from util import admin 161 from myapp.models import MyModel 162 163 class MyModelAdmin(admin.ModelAdmin): 164 pass 165 166 167Low level API examples 168====================== 169How to get make a thumbnail in your python code:: 170 171 from sorl.thumbnail import get_thumbnail 172 173 im = get_thumbnail(my_file, '100x100', crop='center', quality=99) 174 175 176How to delete a file, its thumbnails as well as references in the Key Value 177Store:: 178 179 from sorl.thumbnail import delete 180 181 delete(my_file) 182 183