From d00df53a62a2061ddd40fdc8956f9b9b4a48067b Mon Sep 17 00:00:00 2001
From: Daniel Kirkham <d.kirkham@kirkham.id.au>
Date: Sat, 17 Feb 2024 12:10:08 +1100
Subject: [PATCH] Document the vary_fields property for custom image filters

---
 CHANGELOG.txt                          |  1 +
 docs/extending/custom_image_filters.md | 13 +++++++++++++
 docs/releases/6.2.md                   |  1 +
 3 files changed, 15 insertions(+)

diff --git a/CHANGELOG.txt b/CHANGELOG.txt
index fbb83aaf76..e72d5b4106 100644
--- a/CHANGELOG.txt
+++ b/CHANGELOG.txt
@@ -49,6 +49,7 @@ Changelog
  * Docs: Add note about `prefers-reduced-motion` to the accessibility documentation (Roel Koper)
  * Docs: Update deployment instructions for Fly.io (Jeroen de Vries)
  * Docs: Add better docs for generating URLs on creating admin views (Shlomo Markowitz)
+ * Docs: Document the `vary_fields` property for custom image filters (Daniel Kirkham)
  * Maintenance: Use `DjangoJSONEncoder` instead of custom `LazyStringEncoder` to serialize Draftail config (Sage Abdullah)
  * Maintenance: Refactor image chooser pagination to check `WAGTAILIMAGES_CHOOSER_PAGE_SIZE` at runtime (Matt Westcott)
  * Maintenance: Exclude the `client/scss` directory in Tailwind content config to speed up CSS compilation (Sage Abdullah)
diff --git a/docs/extending/custom_image_filters.md b/docs/extending/custom_image_filters.md
index 0a0160f9b0..6a0abe990d 100644
--- a/docs/extending/custom_image_filters.md
+++ b/docs/extending/custom_image_filters.md
@@ -36,3 +36,16 @@ Use the filter in a template, like so:
 
 {% image page.photo width-400 blur-7 %}
 ```
+
+If your custom image filter depends on fields within the `Image`, for instance those defining the focal point, add a `vary_fields` property listing those field names to the subclassed `FilterOperation`. This ensures that a new rendition is created whenever the focal point is changed:
+
+```python
+class BlurOutsideFocusPointOperation(FilterOperation):
+    vary_fields = (
+        "focal_point_width",
+        "focal_point_height",
+        "focal_point_x",
+        "focal_point_y",
+    )
+    # ...
+```
diff --git a/docs/releases/6.2.md b/docs/releases/6.2.md
index c04a387f70..9dfcfd37de 100644
--- a/docs/releases/6.2.md
+++ b/docs/releases/6.2.md
@@ -70,6 +70,7 @@ This feature was implemented by Albina Starykova, with support from the Wagtail
  * Add note about `prefers-reduced-motion` to the accessibility documentation (Roel Koper)
  * Update deployment instructions for Fly.io (Jeroen de Vries)
  * Add better docs for generating URLs on [creating admin views](../extending/admin_views.md) (Shlomo Markowitz)
+ * Document the `vary_fields` property for [custom image filters](custom_image_filters) (Daniel Kirkham)
 
 ### Maintenance