Metadata-Version: 2.1
Name: django-thumbor
Version: 0.6.0
Summary: A django application to resize images using the thumbor service
Home-page: http://github.com/ricobl/django-thumbor/
Author: Enrico Batista da Luz
Author-email: rico.bl@gmail.com
License: django-thumbor is licensed under the MIT license. For more information, please see LICENSE file.
Classifier: License :: OSI Approved :: MIT License
License-File: LICENSE
Requires-Dist: Django>=1.4
Requires-Dist: libthumbor>=1.2.0

django-thumbor
==============

.. image:: https://travis-ci.org/ricobl/django-thumbor.png?branch=master
    :target: https://travis-ci.org/ricobl/django-thumbor
    :alt: CI status on Travis CI

.. image:: http://img.shields.io/pypi/v/django-thumbor.svg
    :target: https://pypi.python.org/pypi/django-thumbor/
    :alt: Latest django-thumbor PyPI version

.. image:: https://img.shields.io/pypi/dm/django-thumbor.svg
    :target: https://pypi.python.org/pypi/django-thumbor/
    :alt: Number of downloads for django-thumbor on PyPI


A django application to resize images using the
`thumbor <https://github.com/globocom/thumbor>`_ service.

Usage
-----

Both ``thumbor_url`` templatetag and the ``generate_url`` helper uses the same
arguments as `libthumbor <https://github.com/heynemann/libthumbor>`_, you can
check the `wiki <https://github.com/heynemann/libthumbor/wiki>`_ for more info.

On templates:

.. code-block:: html

    {% load thumbor_tags %}
    <img src="{% thumbor_url '/media/image.jpg' width=300 %}" width="300" />

    or

    {% load thumbor_tags %}
    <img src="{% thumbor_url model.image_field width=300 %}" width="300" />

If you need the result in a template variable, use `assign_thumbor_url` instead.

    {% load thumbor_tags %}
    {% assign_thumbor_url '/media/image.jpg' width=300 as thumb_url %}
    <img src="{{ thumb_url }}" width="300" />

**Filters**

Split `filters <https://github.com/thumbor/thumbor/wiki/Filters>`_ with
``:`` (or use a ``list`` object):

.. code-block:: html

    {% load thumbor_tags %}
    <img src="{% thumbor_url url filters='watermark(http://domain.com/watermark.png,-10,-10,20):brightness(10)' %}" />
    <img src="{% thumbor_url url filters=filter_list %}" />

On code:

.. code-block:: python

    from django_thumbor import generate_url
    resized = generate_url("/media/image.jpg", width=300)


**Re-using argument sets (aliases)**

You can re-use argument sets through globally defined aliases. This prevents
repeating thumbnail parameters all over the code and can improve thumbor
performance because thumbnails are re-used as well. If you're migrating
from django-easy-thumbnails, you'll find the pattern very familiar, and it
should make porting much more straight-forward.

On templates:

.. code-block:: html

    {% load thumbor_tags %}
    <img src="{% thumbor_url '/media/image.jpg' alias="thumb-square" %}" />

On code:

.. code-block:: python

    from django_thumbor import generate_url
    resized = generate_url("/media/image.jpg", alias="thumb-square")

And in your ``settings.py``:

.. code-block:: python

    THUMBOR_ALIASES = {
        'thumb-square': {
            'width': 300,
            'height': 300,
            'filters': ['brightness(10)']}
    }


**Override server address**

There is an extra parameter to specify a custom server to be used instead of
``settings.THUMBOR_SERVER``.

On templates:

.. code-block:: html

    {% load thumbor_tags %}
    <img src="{% thumbor_url '/media/image.jpg' thumbor_server='http://localhost:8888/foo' width=300 %}" width="300" />

On code:

.. code-block:: python

    from django_thumbor import generate_url
    custom_server = "http://localhost:8888/foo"
    resized = generate_url(
        "/media/image.jpg", thumbor_server=custom_server, width=300)


Installation
------------

.. code-block:: bash

    pip install django-thumbor


Configuration
-------------

Add the app to the ``INSTALLED_APPS``:

.. code-block:: python

    INSTALLED_APPS = (
        # ...
        'django_thumbor',
    )

Here are the default settings that you can override:

.. code-block:: python

    # The host serving the thumbor resized images
    THUMBOR_SERVER = 'http://localhost:8888'

    # The prefix for the host serving the original images
    # This must be a resolvable address to allow thumbor to reach the images
    THUMBOR_MEDIA_URL = 'http://localhost:8000/media'

    # If you want the static to be handled by django thumbor
    # default as False, set True to handle it if you host your statics
    THUMBOR_STATIC_ENABLED = False

    # The prefix for the host serving the original static images
    # this must be a resolvable address to allow thumbor to reach the images
    THUMBOR_STATIC_URL = 'http://localhost:8000/static'

    # The same security key used in the thumbor service to
    # match the URL construction
    THUMBOR_SECURITY_KEY = 'MY_SECURE_KEY'

    # Default arguments passed to the `generate_url` helper or
    # the `thumbor_url` templatetag
    THUMBOR_ARGUMENTS = {}

    # An alias represents a named set of arguments to the generate_url function
    # or thumbor_url template tag. Use it to share general thumbnail
    # configurations without repeating yourself.
    THUMBOR_ALIASES = {}


Contributing
------------

Install
.......

Fork, clone, create a virtualenv and run:

.. code-block:: bash

    git clone git://github.com/ricobl/django-thumbor.git
    cd django-thumbor
    pipenv shell
    make install

Test
....

Add tests on ``testproject/tests``, add code and run:

.. code-block:: bash

    make test

Test Server
...........

- Instal thumbor server: ``pip install thumbor``
- Run thumbor: ``thumbor``
- Run local server: ``make run``
- visit `http://127.0.0.1:8000/ <http://127.0.0.1:8000/>`_:
