Installation and Configuration¶
Note
upgrading from 0.8.7? Checkout 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 Permissions section.
secure downloads¶
Warning
File download permissions are an experimental feature. The api may change at any time.
See 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 about Django’s logging configuration.