django-thumbnail-maker 0.0.6
Thumbnail maker for Django
License: BSD

.. image:: https://travis-ci.org/infinityxxx/django-thumbnail-maker.svg?branch=master
    :target: https://travis-ci.org/infinityxxx/django-thumbnail-maker
.. image:: https://coveralls.io/repos/infinityxxx/django-thumbnail-maker/badge.png?branch=master
    :target: https://coveralls.io/r/infinityxxx/django-thumbnail-maker?branch=master
.. image:: https://badge.fury.io/py/django-thumbnail-maker.svg
    :target: http://badge.fury.io/py/django-thumbnail-maker

Auto-generator of thumbnails for Django, using sorl-thumbnail.

Features
========

- Auto-genarates thumbnails using sorl-thumbnail while uploading (saving) images
- You can use any engines & plugins you usually use with sorl-thumbnail
- The application does not replace thumbnail templatetag and you can use everything you want from sorl-thumbnail
- Command to auto-generate missing thumbnails

How to Use
==========

Get the code
------------

Get the code for the latest stable release use pip::

   $ pip install django-thumbnail-maker

Configure your project
-----------------------

Register ``'thumbnail_maker'``, in the ``INSTALLED_APPS`` section of
your project's settings anywhere after ``'sorl.thumbnail'`` app (assume you already installed ``sorl-thumbnail``)::

    INSTALLED_APPS = (
        'django.contrib.auth',
        'django.contrib.admin',
        'django.contrib.sites',
        'django.contrib.comments',
        'django.contrib.sessions',
        'django.contrib.messages',
        'django.contrib.contenttypes',
        ...
        'sorl.thumbnail',
        ...
        'thumbnail_maker',
    )

Set up required thumb formats in ``THUMBNAIL_MAKER_FORMATS`` dictionary.
Keys are the names for your formats (could be any string).
Values are tuples of length 2: first element is a geometry string (used in ``sorl-thumbnail``),
second is a dictionary with options (``crop``, ``quality``, ``padding``, ``format``, etc.)::

    THUMBNAIL_MAKER_FORMATS = {
       'banner':   ('400x300', {'crop': 'center',
                                'quality': 90}),
       '50x50':    ('50x50',   {}),
       'any_name': ('5x277',   {'padding': True})
   }

You can set up ``THUMBNAIL_MAKER_DEBUG`` setting.
By default it is set to ``False`` in order to pass exceptions
while saving models or while generating batch of thumbnails.
This setting is not required. Usage::

    THUMBNAIL_MAKER_DEBUG = True


Set up your model's field
-------------------------

Use ``ImageWithThumbnailsField`` and ``thumbs`` option, where ``thumbs`` is a tuple of thumb format names
(keys from ``THUMBNAIL_MAKER_FORMATS`` dictionary)::

    from django.db import models
    from thumbnail_maker.fields import ImageWithThumbnailsField

    class Item(models.Model):
        image = ImageWithThumbnailsField(
            upload_to='somewhere',
            thumbs=('banner', '50x50'),
        )


Templates usage
---------------

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

    {% load thumbnail_maker %}

A simple usage::

    {% usethumbnail item.image "banner" as im %}
        <img src="{{ im.url }}" width="{{ im.width }}" height="{{ im.height }}">
    {% endusethumbnail %}

    {% usethumbnail item.image "50x50" as im %}
        <img src="{{ im.url }}" width="{{ im.width }}" height="{{ im.height }}">
    {% endusethumbnail %}

You can also use string paths instead of image objects::

    {% usethumbnail "dummy/image.png" "50x50" as im %}
        <img src="{{ im.url }}" width="{{ im.width }}" height="{{ im.height }}">
    {% endusethumbnail %}

Management commands usage
-------------------------

Django-thumbnail-maker comes with a manage.py command to generate missing thumbs.
You can use it while ::

    ./manage.py make_thumbnails <app>.<model> <field>

In case you want to make all thumbs replacing old ones, use ``--force`` option::

    ./manage.py make_thumbnails --force <app>.<model> <field>