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