diff --git a/docs/extending/rich_text_internals.md b/docs/extending/rich_text_internals.md index 76966c827e..c342203e26 100644 --- a/docs/extending/rich_text_internals.md +++ b/docs/extending/rich_text_internals.md @@ -42,7 +42,7 @@ which is converted into an `img` element when rendered: alt="A pied wagtail" class="richtext-image left" height="294" - src="/media/images/pied-wagtail.width-500_ENyKffb.jpg" + src="/media/images/pied-wagtail.width-500.jpg" width="500" /> ``` diff --git a/docs/reference/jinja2.md b/docs/reference/jinja2.md index 201dca55df..5f81903758 100644 --- a/docs/reference/jinja2.md +++ b/docs/reference/jinja2.md @@ -92,7 +92,13 @@ Browsers will select the most appropriate image to load based on [responsive ima The [`sizes`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#sizes) attribute is essential unless you store the output of `srcset_image` for later use. ```html+jinja -{{ srcset_image(page.header_image, "fill-{512x100,1024x200}", sizes="100vw", class="header-image") }} +{{ srcset_image(page.photo, "width-{400,800}", sizes="(max-width: 600px) 400px, 80vw") }} +``` + +This outputs: + +```html +A pied Wagtail ``` Or resize an image and retrieve the renditions for more bespoke use: @@ -104,19 +110,39 @@ Or resize an image and retrieve the renditions for more bespoke use: ### `picture()` -Resize or convert an image, rendering a `` tag including multiple `source` formats with `srcset` for multiple sizes. +Resize or convert an image, rendering a `` tag including multiple `source` formats with `srcset` for multiple sizes, and a fallback `` tag. Browsers will select the [first supported image format](https://web.dev/learn/design/picture-element/#image-formats), and pick a size based on [responsive image rules](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images). `picture` can render an image in multiple formats: ```html+jinja -{{ picture(page.header_image, "format-{avif,jpeg}") }} +{{ picture(page.photo, "format-{avif,webp,jpeg}|width-400") }} +``` + +This outputs: + +```html + + + + A pied Wagtail + ``` Or render multiple formats and multiple sizes like `srcset_image` does. The [`sizes`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#sizes) attribute is essential when the picture tag renders images in multiple sizes: ```html+jinja -{{ picture(page.header_image, "format-{avif,jpeg}|fill-{512x100,1024x200}", sizes="100vw") }} +{{ picture(page.header_image, "format-{avif,webp,jpeg}|width-{400,800}", sizes="80vw") }} +``` + +This outputs: + +```html + + + + A pied Wagtail + ``` Or resize an image and retrieve the renditions for more bespoke use: diff --git a/docs/releases/5.2.md b/docs/releases/5.2.md index 0ae4f1b6fc..0c30b67552 100644 --- a/docs/releases/5.2.md +++ b/docs/releases/5.2.md @@ -25,11 +25,27 @@ The page explorer listing view has been redesigned to allow improved navigation ### Responsive & multi-format images with the picture tag -Wagtail has new template tags to reduce the performance and environmental footprint of images: +Wagtail has new template tags to reduce the loading time and environmental footprint of images: * The `picture` tag generates images in multiple formats and-or sizes in one batch, creating an HTML `` tag. * The `srcset_image` tag generates images in multiple sizes, creating an `` tag with a `srcset` attribute. +As an example, the `picture` tag allows generating six variants of an image in one go: + +```html+django +{% picture page.photo format-{avif,webp,jpeg} width-{400,800} sizes="80vw" %} +``` + +This outputs: + +```html + + + + A pied Wagtail + +``` + We expect those changes to greatly reduce the weight of images for all Wagtail sites. We encourage all site implementers to consider using them to improve the performance of the sites and reduce their carbon footprint. For further details, For more details, see [](multiple_formats) and [](responsive_images). Those new template tags are also supported in Jinja templates, see [](jinja2) for the Jinja API. This feature was developed by Paarth Agarwal and Thibaud Colas as part of the Google Summer of Code program and a [partnership with the Green Web Foundation](https://www.thegreenwebfoundation.org/news/working-with-the-wagtail-community-on-the-summer-of-code/) and Green Coding Berlin, with support from Dan Braghiș, Thibaud Colas, Sage Abdullah, Arne Tarara (Green Coding Berlin), and Chris Adams (Green Web Foundation). We also thank Aman Pandey for introducing [AVIF support](image_file_formats) in Wagtail 5.1, Andy Babic for creating [`AbstractImage.get_renditions()`](image_renditions_multiple) in the same release; and Storm Heg, Mitchel Cabuloy, Coen van der Kamp, Tom Dyson, and Chris Lawton for their feedback on [RFC 71](https://github.com/wagtail/rfcs/pull/71). diff --git a/docs/topics/images.md b/docs/topics/images.md index 396e81c69a..6150f06d98 100644 --- a/docs/topics/images.md +++ b/docs/topics/images.md @@ -36,35 +36,65 @@ Note that a space separates `[image]` and `[resize-rule]`, but the resize rule m To render an image in multiple formats, you can use the `picture` tag: ```html+django -{% picture page.photo width-400 format-{avif,jpeg} %} +{% picture page.photo format-{avif,webp,jpeg} width-400 %} ``` -Compared to `image`, this will render a `` element with one `` element per format. The browser [picks the first format it supports](https://web.dev/learn/design/picture-element/#source), or defaults to a fallback `` element. +Compared to `image`, this will render a `` element with a fallback `` within and one `` element per extra format. The browser [picks the first format it supports](https://web.dev/learn/design/picture-element/#source), or defaults to the fallback `` element. For example, the above will render HTML similar to: -`picture` can also be used with responsive image resize rules. +```html + + + + A pied Wagtail + +``` + +In this case, if the browser supports the [AVIF](https://en.wikipedia.org/wiki/AVIF) format it will load the AVIF file. Otherwise, if the browser supports the [WebP](https://en.wikipedia.org/wiki/WebP) format, it will try to load the WebP file. If none of those formats are supported, the browser will load the JPEG image. The order of the provided formats isn’t configurable – Wagtail will always output source elements in the following order: AVIF, WebP, JPEG, PNG, GIF. This ensures the most optimized format is provided whenever possible. + +The `picture` tag can also be used with multiple image resize rules to generate responsive images. (responsive_images)= ## Responsive images -Wagtail provides `picture` and `srcset_image` template tags which can generate an `` tag with a `srcset` attribute. This allows browsers to select the most appropriate image file to load based on [responsive image rules](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images). +Wagtail provides `picture` and `srcset_image` template tags which can generate image elements with `srcset` attributes. This allows browsers to select the most appropriate image file to load based on [responsive image rules](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images). -The syntax for `srcset_image` is the same as `image, with two exceptions: +The syntax for `srcset_image` is the same as `image`, with two exceptions: ```html+django -{% srcset_image [image] [resize-rule-with-brace-expansion] sizes="100vw" %} +{% srcset_image [image] [resize-rule-with-brace-expansion] sizes="[my source sizes]" %} ``` -- The resize rule should be provided with multiple sizes in a brace-expansion pattern, like `width-{200,400}`. This will generate the `srcset` attribute, with as many URLs as there are sizes defined in the resize rule. +- The resize rule should be provided with multiple sizes in a brace-expansion pattern, like `width-{200,400}`. This will generate the `srcset` attribute, with as many URLs as there are sizes defined in the resize rule, and one width descriptor per URL. The first provided size will always be used as the `src` attribute, and define the image’s width and height attributes, as a fallback. - The [`sizes`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#sizes) attribute is essential. This tells the browser how large the image will be displayed on the page, so that it can select the most appropriate image to load. -Here is an example with the `picture` tag: +Here is an example of `srcset_image` in action, generating an `srcset` attribute: ```html+django -{% picture page.photo fill-{512x100,1024x200} format-{avif,jpeg} sizes="100vw" %} +{% srcset_image page.photo width-{400,800} sizes="(max-width: 600px) 400px, 80vw" %} ``` -This will generate a `` element with one `` for AVIF and one fallback `` with JPEG. Both the source and fallback image will have the `sizes` attribute, and a `srcset` with two URLs each. +This outputs: + +```html +A pied Wagtail +``` + +And here is an example with the `picture` tag: + +```html+django +{% picture page.photo format-{avif,webp,jpeg} width-{400,800} sizes="80vw" %} +``` + +This outputs: + +```html + + + + A pied Wagtail + +``` (available_resizing_methods)= diff --git a/docs/topics/writing_templates.md b/docs/topics/writing_templates.md index 7cec846ef0..02c67b9f46 100644 --- a/docs/topics/writing_templates.md +++ b/docs/topics/writing_templates.md @@ -98,6 +98,42 @@ For example: See [](image_tag) for full documentation. +### Images in multiple formats + +The `picture` tag works like `image`, but allows specifying multiple formats to generate a `` element with `` elements and a fallback ``. + +For example: + +```html+django +{% load wagtailimages_tags %} +... + +{% picture page.photo format-{avif,webp,jpeg} width-400 %} +``` + +See [](multiple_formats) for full documentation. + +### Images in multiple sizes + +The `srcset_image` tag works like `image`, but allows specifying multiple sizes to generate a `srcset` attribute and leverage [responsive image rules](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images). + +For example: + +```html+django +{% load wagtailimages_tags %} +... + +{% srcset_image page.photo width-{400,800} sizes="(max-width: 600px) 400px, 80vw" %} +``` + +This can also be done with `picture`, to generate multiple formats and sizes at once: + +```html+django +{% picture page.photo format-{avif,webp,jpeg} width-{400,800} sizes="80vw" %} +``` + +See [](responsive_images) for full documentation. + (rich_text_filter)= ## Rich text (filter)