djblets.util.templatetags.djblets_images¶

Image-related template tags.

save_image_to_storage(image, storage, filename)¶

Save an image to storage.

crop_image(f, x, y, width, height)¶

Crops an image at the specified coordinates and dimensions, returning the resulting URL of the cropped image.

thumbnail(f: Union[File, str], size: Union[str, tuple[Optional[int], Optional[int]]] = '400x100', *, create_if_missing: bool = True, storage: Optional[Storage] = None) → Optional[str]¶

Create a thumbnail of the given image.

This will create a thumbnail of the given file, which may be a file path within storage, a File instance representing a file in storage, or a file instance retrieved from a :py:class:~django.db.models.FileField`.

The thumbnail will be of the given size. This size can either be specified as a string of WIDTHxHEIGHT (in pixels), or a 2-tuple. If the size is a tuple and one of the values is None, that value will be set automatically to preserve the aspect ratio.

If the file format is not supported, then the file path will be returned as-is.

Changed in version 5.0:

• Added create_if_missing and storage options.

• Added support for working with general File objects or file paths within storage, when providing the storage parameter.

Parameters:

• f (django.db.models.fields.files.FieldFile) –

  The file path within storage, File instance, or a FileField-backed file.

  if not providing a field-backed file, then storage must be provided.

  Changed in version 5.0: This may now be a file path within storage or a File instance.

• size (str or tuple of int) –

  The thumbnail constraint size.

  This can either be a string in WIDTHxHEIGHT form, or a tuple in (width, height) form. In the latter, the height is optional.

• create_if_missing (bool, optional) –

  Whether to create the thumbnail if one does not already exist.

  If False, the existing thumbnail URL will be returned if it exists, but a new one will not otherwise be created.

  New in version 5.0.

• storage (django.core.files.storage.Storage, optional) –

  The storage backend for the file.

  This is required if the file does not provide its own storage attribute, and is ignored if it does.

  New in version 5.0.

Returns:

The URL to the thumbnail.

This will be None if the thumbnail does not exist and passing create_if_missing=False.

Return type:

str

Raises:

ValueError – The thumbnail size was not in a valid format.

build_srcset(sources)¶

Return the source set attribute value for the given sources.

The resulting sources will be sorted by value, with the pixel density (x) values coming before width (w) values.

Parameters:

sources (dict) – A mapping of descriptors (e.g., '2x' or '512w') that describe the requirement for the source to be shown to URLs.

Returns:

The returned srcset attribute value.

Return type:

unicode

srcset(sources)¶

Render the source set attribute value for the given sources.

The resulting sources will be sorted by value, with the pixel density (x) values coming before width (w) values.

Parameters:

sources (dict) – A mapping of descriptors (e.g., '2x' or '512w') that describe the requirement for the source to be shown to URLs.

Returns:

The rendered srcset attribute value.

Return type:

unicode

image_source_attrs(context, nodelist, *options)¶

Render source attributes for an image tag.

This will render src="..." srcset="..." attributes for an <img> tag, based on the sources provided in the tag’s content. There should be one source definition per line (with an optional trailing comma) in the form of:

<descriptor> <URL>

These will get turned into a srcset, and the 1x descriptor (which is required) will be set as the src attribute.

Parameters:

block_content (unicode) – The block content containing image sources.

Returns:

Attributes for the <img> tag.

Example

<img {% image_source_attrs %}
     1x {%  static "images/myimage.png" %}
     2x {%  static "images/myimage@2x.png" %}
     3x {%  static "images/myimage@3x.png" %}
     {% end_image_source_attrs %}>