.. _installation_and_configuration:
Installation and Configuration
==============================
.. note:: upgrading from 0.8.7? Checkout :ref:`upgrading`.
Getting the latest release
--------------------------
The easiest way to get ``django-filer`` is simply install it with `pip`_::
$ pip install django-filer
If you are feeling adventurous you can get
`the latest sourcecode from github `_ or add
http://stefanfoulis.github.com/django-filer/unstable_releases/ to ``find-links`` for the latest
alpha and beta releases.
Dependencies
------------
* `Django`_ >=1.3.1,<1.5
* `django-mptt`_ >=0.5.1,<0.6
* `easy_thumbnails`_ >= 1.0
* `django-polymorphic`_ >=0.2
* `PIL`_ 1.1.7 (with JPEG and ZLIB support) I recommend using `Pillow`_ instead.
* ``django.contrib.staticfiles``
Since the `PIL package on pypi `_ can be notoriously hard to install on some
platforms it is not listed in the package dependencies in ``setup.py`` and won't
be installed automatically. Please make sure you install `PIL`_ with JPEG and
ZLIB support installed. I recommend `Pillow`_ a better
packaged fork of `PIL`_).
Configuration
-------------
Add ``"filer"`` and related apps to your project's ``INSTALLED_APPS`` setting and run ``manage.py syncdb``
(or ``manage.py migrate`` if you're using `South`_).::
INSTALLED_APPS = [
...
'filer',
'easy_thumbnails',
...
]
Note that `easy_thumbnails`_ also has database tables and needs a ``syncdb`` or
``migrate``.
Static media
............
In order to operate properly, django-filer needs some js and css files. They
are located in the ``static/filer`` directory in the ``filer`` package. Use
`django.contrib.staticfiles`_ (or `django-staticfiles`_) to have them
automatically served.
subject location aware cropping
...............................
It is possible to define the *important* part of an image (the
*subject location*) in the admin interface for django-filer images. This is
very useful when later resizing and cropping images with easy_thumbnails. The
image can then be cropped automatically in a way, that the important part of
the image is always visible.
To enable automatic subject location aware cropping of images replace
``easy_thumbnails.processors.scale_and_crop`` with
``filer.thumbnail_processors.scale_and_crop_with_subject_location`` in the
``THUMBNAIL_PROCESSORS`` setting::
THUMBNAIL_PROCESSORS = (
'easy_thumbnails.processors.colorspace',
'easy_thumbnails.processors.autocrop',
#'easy_thumbnails.processors.scale_and_crop',
'filer.thumbnail_processors.scale_and_crop_with_subject_location',
'easy_thumbnails.processors.filters',
)
To crop an image and respect the subject location::
{% load thumbnail %}
{% thumbnail obj.img 200x300 crop upscale subject_location=obj.img.subject_location %}
permissions
...........
.. WARNING:: File permissions are an experimental feature. The api may change at any time.
See :ref:`permissions` section.
secure downloads
................
.. WARNING:: File download permissions are an experimental feature. The api may change at any time.
See :ref:`secure_downloads` section.
debugging and logging
.....................
While by default ``django-filer`` usually silently skips icon/thumbnail
generation errors, two options are provided to help when working with ``django-filer``:
* ``FILER_DEBUG``: Boolean, controls whether bubbling up any ``easy-thumbnails``
exception (typically if an image file doesn't exists); is ``False`` by default;
* ``FILER_ENABLE_LOGGING``: Boolean, controls whether logging the above exceptions.
It requires proper django logging configuration for default logger or
``filer`` logger. Please see https://docs.djangoproject.com/en/dev/topics/logging/
for further information abount django logging configuration.
.. _django-filer: https://github.com/stefanfoulis/django-filer/
.. _django-staticfiles: http://pypi.python.org/pypi/django-staticfiles/
.. _django.contrib.staticfiles: http://docs.djangoproject.com/en/1.3/howto/static-files/
.. _Django: http://djangoproject.com
.. _django-polymorphic: https://github.com/bconstantin/django_polymorphic
.. _easy_thumbnails: https://github.com/SmileyChris/easy-thumbnails
.. _sorl.thumbnail: http://thumbnail.sorl.net/
.. _PIL: http://www.pythonware.com/products/pil/
.. _django-mptt: https://github.com/django-mptt/django-mptt/
.. _Pillow: http://pypi.python.org/pypi/Pillow/
.. _pip: http://pypi.python.org/pypi/pip
.. _South: http://south.aeracode.org/