Out-of-band processing for sorl-thumbnail thumbnails.
Project description
Out-of-band processing for sorl-thumbnail thumbnails.
Installation & Setup
Installation
Installation is as easy as pip install sorl-url though the latest version is always available on GitHub.
Setup
Add sorl-url to your settings.INSTALLED_APPS.
Add url(r'^thumbnails/', include('sorl_url.urls')) to your URL configuration.
Configure your defaults (see Usage below).
Requirements
Base Requirements
sorl-thumbnail 11.12+
sorl-thumbnail
Mikko Hellsing’s excellent sorl-thumbnail is the only direct requirement for this project.
You can read more about sorl-thumbnail, its requirements and how it is installed and configured at Read the Docs.
Usage
The core workflow is built around usage through a template tag named image_url in the sorl_url template tag library.
sorl_url does not serve images directly. It generates them as sorl-thumbnail would (storing them in a cache via settings.THUMBNAIL_STORAGE) and then redirects to the URL of the generated image.
URL Structure
sorl-url generates URLs of the form: /prefix/MODEL_NAME/FIELD_NAME/KEY.ext?config=OPTIONS
prefix is dictated by the location at which the sorl-url views are included in the URLConf
OPTIONS is a configuration including the size and other options signed and obfuscated by the django.core.signing module described in URL Arguments below.
Note: the config query string argument is mandatory. Failure to provide a config will result in a 404.
URL Arguments
Image options are passed via the config query string argument. The values are obfuscated but not enscrypted. They are serialized, compressed and signed by django.core.signing.
Default options specified in SORL_URL_CONFIG and other sorl settings are not included in the query string. However, the signature is salted with a variety of attributes, including the underlying filename and a hash of all relevant settings to ensure that as underlying attributes and settings are updated, the URL will change as well. Note that this means that a change to SORL_URL_CONFIG, for example, will result in all URLs being updated. This may or may not result in new images being generated by sorl (depending on what has been changed).
Debugging: To easily see what arguments are being passed for rendering, simply set settings.THUMBNAIL_DEBUG to True and append &echo=True to any generated URL to see what options are being passed.
Configuring Settings
The available options and defaults are controlled by the SORL_URL_CONFIG setting.
SORL_URL_CONFIG must be a dictionary-like object with keys corresponding to the MODEL_NAME URL component and a dictionary-like value representing the model configuration.
Additionally SORL_URL_PERMANENT_REDIRECT (default: False) can be used to control the type of redirect that is used.
Model Configuration
Each model configuration offers the following options:
model: either a model class or the Django-style dotted name (app_label.ModelName) (required)
fields: a list of the attributes on model that should be exposed by this configuration; alternatively a 2-tuple of the format (attr_name, options) where options is a dictionary containing default to be passed to the sorl backend’s get_thumbnail method (required)
backend: the sorl backend, as a string representing the module path, to be used (optional; defaults to ``sorl.thumbnail.default.backend``)
key_field: the field to be used in object lookups for the key portion of the URL (optional; defaults to ``id``)
key_filter: a transformation function to be applied to the key URL component to ensure it is properly prepared for the ORM (optional; defaults to ``lambda x: int(x)``)
options: a dictionary containing default options to be passed to the sorl backend’s get_thumbnail method. Individual fields may override these options. (optional; defaults to ``{}``)
Configuration Examples
A minimal configuration might look like:
SORL_URL_CONFIG = { 'profiles': { 'model': 'profiles.Profile', 'fields': ['avatar'], } }
The above configuration would mean that the following URL would be valid: /prefix/profiles/avatar/1.png?config=CONFIG
A more advanced configuration might look like:
SORL_URL_CONFIG = { 'profiles': { 'model': 'profiles.Profile', 'fields': [ ('avatar', { 'format': 'PNG', 'crop': 'top', 'upscale': True }), ('background': { 'format': 'JPEG', 'quality': 90, 'colorspace': 'GRAY' } ) ], 'key_field': 'user__username', 'key_filter': None # The default is lambda x: int(x), # but None implies a no-op (lambda x: x) } }
The above configuration would mean that the following URLs would be exposed:
/prefix/profiles/avatar/1.png?config=CONFIG
/prefix/profiles/background/1.jpg?config=CONFIG
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.