Using daguerre

{% adjust %}

The easiest way to use Daguerre is through the {% adjust %} template tag:

{% load daguerre %}
<img src="{% adjust my_model.image width=128 height=256 %}" />

daguerre works directly with any ImageField (or storage path). There is no magic. You don’t need to change your models. It Just Works.

Let’s be lazy

So the {% adjust %} tag renders as a URL, which gets an adjusted image, right? Well, yes, but in a very lazy fashion. It actually renders a URL to an adjustment view, which runs the adjustment (if necessary), and then redirects the user to the actual adjusted image’s URL.

The upshot is that no matter how many {% adjust %} tags you have on a page, it will render as quickly when the thumbnails already exist as it will when the thumbnails still need to be created. The thumbnails will then be filled in as the user starts to request them.

Note

The adjustment view has some light security in place to make sure that users can’t run arbitrary image resizes on your servers.

Different adjustments

The {% adjust %} tag currently supports three different adjustments: fit, fill, and crop. These can be passed in as an additional parameter to the tag:

<img src="{% adjust my_model.image width=128 height=256 adjustment="fit" %}" />

Take this picture:

../_images/lenna.png

Full size: 512x512

Let’s use {% adjust %} with width 128 (25%) and height 256 (50%), with each of the three adjustments.

“fit” “fill” (default) “crop”
../_images/lenna_fit.png ../_images/lenna_fill.png ../_images/lenna_crop.png
Fits the entire image into the given dimensions without distorting it. Fills the entire space given by the dimensions by cropping to the same width/height ratio and then scaling. Crops the image to the given dimensions without any resizing.

Note

If you have defined Areas for an image in the admin, those will be protected as much as possible (according to their priority) when using the crop or fill adjustments. Otherwise, any cropping will be done evenly from opposing sides.

Getting adjusted width and height

{% load daguerre %}
{% adjust my_model.image width=128 height=128 adjustment="fit" as image %}
<img src="{{ image }}" width={{ image.width }} height={{ image.height }} />

The object being set to the image context variable is an AdjustmentInfoDict instance. In addition to rendering as the URL for an image, this object provides access to some other useful pieces of information—in particular, the width and height that the adjusted image will have, based on the width and height of the original image and the parameters given to the tag. This can help you avoid changes to page flow as adjusted images load.

Named crops (advanced)

If you are defining Areas in the admin, you can refer to these by name to pre-crop images before applying the adjustment you’ve selected. For example:

{% load daguerre %}
<img src="{% adjust my_model.image width=128 height=128 adjustment="fit" crop="face" %}" />

This would first crop the image to the “face” Area (if available) and then fit that cropped image into a 128x128 box.

Note

If a named crop is being used, Areas will be ignored even if you’re using a fill or crop adjustment. (This may change in the future.)

{% adjust_bulk %}

If you are using a large number of similar adjustments in one template - say, looping over a queryset and adjusting the same attribute each time - you can save yourself queries by using {% adjust_bulk %}.

{% load daguerre %}
{% adjust_bulk my_queryset "method.image" width=200 height=400 as adjusted_list %}
{% for my_model, image in adjusted_list %}
  <img src="{{ image }}" />
{% endfor %}

The syntax is similar to {% adjust %}, except that:

  • as <varname> is required.
  • an iterable (my_queryset) and an lookup to be performed on each item in the iterable ("method.image") are provided in place of an image file or storage path.
  • {% adjust_bulk %} doesn’t support named crops.

Editing Areas

Daguerre provides a widget which can be used with any ImageField to edit Areas for that image file. Using this widget with a ModelAdmin is as simple as defining appropriate formfield_overrides.

from daguerre.widgets import AreaWidget

class YourModelAdmin(admin.ModelAdmin):
    formfield_overrides = {
        models.ImageField: {'widget': AreaWidget},
    }
    ...