Deprecate the WAGTAIL_AUTO_UPDATE_PREVIEW setting

CHANGELOG.txt

@@ -14,6 +14,7 @@ Changelog
  * Refactor images views to use universal designs (Sage Abdullah)
  * Implement universal listings for workflow usage and page type usage views (Sage Abdullah)
  * Add search and filters to form pages listing (Sage Abdullah)
+ * Deprecate the `WAGTAIL_AUTO_UPDATE_PREVIEW` setting, use `WAGTAIL_AUTO_UPDATE_PREVIEW_INTERVAL = 0` instead (Sage Abdullah)
  * Fix: Prevent page type business rules from blocking reordering of pages (Andy Babic, Sage Abdullah)
  * Fix: Improve layout of object permissions table (Sage Abdullah)
  * Fix: Fix typo in aria-label attribute of page explorer navigation link (Sébastien Corbin)

docs/reference/settings.md

@@ -295,7 +295,11 @@ WAGTAIL_AUTO_UPDATE_PREVIEW = True
 When enabled, the preview panel in the page editor is automatically updated on each change. If set to `False`, a refresh button will be shown and the preview is only updated when the button is clicked.
 This behavior is enabled by default.
 
-To completely disable the preview panel, set [preview modes](wagtail.models.Page.preview_modes) to be empty on your model `preview_modes = []`.
+```{versionchanged} 6.3
+This setting is deprecated. Set `WAGTAIL_AUTO_UPDATE_PREVIEW_INTERVAL = 0` to disable automatic preview updates instead.
+```
+
+(wagtail_auto_update_preview_interval)=
 
 ### `WAGTAIL_AUTO_UPDATE_PREVIEW_INTERVAL`
 
@@ -303,7 +307,11 @@ To completely disable the preview panel, set [preview modes](wagtail.models.Page
 WAGTAIL_AUTO_UPDATE_PREVIEW_INTERVAL = 500
 ```
 
-How often to check for changes made in the page editor before updating the preview. In milliseconds. The default value is `500`.
+The interval (in milliseconds) to automatically check for changes made in the page or snippet editor before updating the preview in the preview panel. The default value is `500`.
+
+If set to `0`, a refresh button will be shown in the panel and the preview is only updated when the button is clicked.
+
+To completely disable previews, set [preview modes](wagtail.models.Page.preview_modes) to be empty on your model (`preview_modes = []`).
 
 (wagtail_editing_session_ping_interval)=
 
@@ -313,7 +321,7 @@ How often to check for changes made in the page editor before updating the previ
 WAGTAIL_EDITING_SESSION_PING_INTERVAL = 10000
 ```
 
-The interval (in milliseconds) to ping the server during an editing session. This is used to indicate that the session is active, as well as to display the list of other sessions that are currently editing the same content. The default value is `10000` (10 seconds). In order to effectively display the sessions list, this value needs to be set to under 1 minute. If set to 0, the interval will be disabled.
+The interval (in milliseconds) to ping the server during an editing session. This is used to indicate that the session is active, as well as to display the list of other sessions that are currently editing the same content. The default value is `10000` (10 seconds). In order to effectively display the sessions list, this value needs to be set to under 1 minute. If set to `0`, the interval will be disabled.
 
 (wagtailadmin_global_edit_lock)=
 

docs/releases/6.3.md

@@ -26,6 +26,7 @@ This release adds formal support for Django 5.1.
  * Refactor images views to use universal designs (Sage Abdullah)
  * Implement universal listings for workflow usage and page type usage views (Sage Abdullah)
  * Add search and filters to form pages listing (Sage Abdullah)
+ * Deprecate the `WAGTAIL_AUTO_UPDATE_PREVIEW` setting, use `WAGTAIL_AUTO_UPDATE_PREVIEW_INTERVAL = 0` instead (Sage Abdullah)
 
 ### Bug fixes
 
@@ -72,6 +73,12 @@ This release adds formal support for Django 5.1.
 
 Python 3.8 is no longer supported as of this release; please upgrade to Python 3.9 or above before upgrading Wagtail.
 
+### Deprecation of the `WAGTAIL_AUTO_UPDATE_PREVIEW` setting
+
+The [`WAGTAIL_AUTO_UPDATE_PREVIEW`](wagtail_auto_update_preview) setting has been deprecated and will be removed in a future release.
+
+To disable the automatic preview update feature, set [`WAGTAIL_AUTO_UPDATE_PREVIEW_INTERVAL = 0`](wagtail_auto_update_preview_interval) in your Django settings instead.
+
 ## Upgrade considerations - changes affecting Wagtail customisations
 
 ## Upgrade considerations - changes to undocumented internals

wagtail/admin/tests/pages/test_preview.py

@@ -15,6 +15,7 @@ from wagtail.test.testapp.models import (
     StreamPage,
 )
 from wagtail.test.utils import WagtailTestUtils
+from wagtail.utils.deprecation import RemovedInWagtail70Warning
 
 
 class TestIssue2599(WagtailTestUtils, TestCase):
@@ -656,6 +657,39 @@ class TestEnablePreview(WagtailTestUtils, TestCase):
         self.assertEqual(refresh_button.get("data-controller"), "w-progress")
         self.assertEqual(refresh_button.text.strip(), "Refresh")
 
+    @override_settings(WAGTAIL_AUTO_UPDATE_PREVIEW=False)
+    def test_disable_auto_update_using_deprecated_setting(self):
+        edit_url = self.get_url_on_edit("edit", self.single)
+        preview_url = self.get_url_on_edit("preview_on_edit", self.single)
+        with self.assertWarnsMessage(
+            RemovedInWagtail70Warning,
+            "`WAGTAIL_AUTO_UPDATE_PREVIEW` is deprecated. "
+            "Set `WAGTAIL_AUTO_UPDATE_PREVIEW_INTERVAL = 0` to disable auto-update "
+            "for previews.",
+        ):
+            response = self.client.get(edit_url)
+
+        self.assertEqual(response.status_code, 200)
+
+        soup = self.get_soup(response.content)
+
+        # Should set the interval value on the controller
+        controller = soup.select_one('[data-controller="w-preview"]')
+        self.assertIsNotNone(controller)
+        self.assertEqual(controller.get("data-w-preview-url-value"), preview_url)
+        interval_value = controller.get("data-w-preview-auto-update-interval-value")
+        self.assertEqual(interval_value, "0")
+
+        # Should not render the spinner
+        spinner = controller.select_one('[data-w-preview-target="spinner"]')
+        self.assertIsNone(spinner)
+
+        # Should render the refresh button with the w-progress controller
+        refresh_button = controller.select_one("button")
+        self.assertIsNotNone(refresh_button)
+        self.assertEqual(refresh_button.get("data-controller"), "w-progress")
+        self.assertEqual(refresh_button.text.strip(), "Refresh")
+
     def test_show_preview_on_revisions_list(self):
         latest_revision = self.single.save_revision(log_action=True)
         history_url = self.get_url_on_edit("history", self.single)

wagtail/admin/ui/side_panels.py

@@ -1,3 +1,5 @@
+import warnings
+
 from django.conf import settings
 from django.urls import reverse
 from django.utils.text import capfirst
@@ -7,6 +9,7 @@ from wagtail import hooks
 from wagtail.admin.ui.components import Component
 from wagtail.admin.userbar import AccessibilityItem
 from wagtail.models import DraftStateMixin, LockableMixin, Page, ReferenceIndex
+from wagtail.utils.deprecation import RemovedInWagtail70Warning
 
 
 class BaseSidePanel(Component):
@@ -353,8 +356,16 @@ class PreviewSidePanel(BaseSidePanel):
 
     @property
     def auto_update_interval(self):
-        if not getattr(settings, "WAGTAIL_AUTO_UPDATE_PREVIEW", True):
-            return 0
+        if hasattr(settings, "WAGTAIL_AUTO_UPDATE_PREVIEW"):
+            warnings.warn(
+                "`WAGTAIL_AUTO_UPDATE_PREVIEW` is deprecated. "
+                "Set `WAGTAIL_AUTO_UPDATE_PREVIEW_INTERVAL = 0` to disable "
+                "auto-update for previews.",
+                RemovedInWagtail70Warning,
+            )
+            if not settings.WAGTAIL_AUTO_UPDATE_PREVIEW:
+                return 0
+
         return getattr(settings, "WAGTAIL_AUTO_UPDATE_PREVIEW_INTERVAL", 500)
 
     def get_context_data(self, parent_context):

wagtail/snippets/tests/test_preview.py

@@ -14,6 +14,7 @@ from wagtail.test.testapp.models import (
     RevisableModel,
 )
 from wagtail.test.utils import WagtailTestUtils
+from wagtail.utils.deprecation import RemovedInWagtail70Warning
 
 
 class TestPreview(WagtailTestUtils, TestCase):
@@ -516,6 +517,41 @@ class TestEnablePreview(WagtailTestUtils, TestCase):
         self.assertEqual(refresh_button.get("data-controller"), "w-progress")
         self.assertEqual(refresh_button.text.strip(), "Refresh")
 
+    @override_settings(WAGTAIL_AUTO_UPDATE_PREVIEW=False)
+    def test_disable_auto_update_using_deprecated_setting(self):
+        edit_url = self.get_url(self.single, "edit", args=(self.single.pk,))
+        preview_url = self.get_url(
+            self.single, "preview_on_edit", args=(self.multiple.pk,)
+        )
+        with self.assertWarnsMessage(
+            RemovedInWagtail70Warning,
+            "`WAGTAIL_AUTO_UPDATE_PREVIEW` is deprecated. "
+            "Set `WAGTAIL_AUTO_UPDATE_PREVIEW_INTERVAL = 0` to disable auto-update "
+            "for previews.",
+        ):
+            response = self.client.get(edit_url)
+
+        self.assertEqual(response.status_code, 200)
+
+        soup = self.get_soup(response.content)
+
+        # Should set the interval value on the controller
+        controller = soup.select_one('[data-controller="w-preview"]')
+        self.assertIsNotNone(controller)
+        self.assertEqual(controller.get("data-w-preview-url-value"), preview_url)
+        interval_value = controller.get("data-w-preview-auto-update-interval-value")
+        self.assertEqual(interval_value, "0")
+
+        # Should not render the spinner
+        spinner = controller.select_one('[data-w-preview-target="spinner"]')
+        self.assertIsNone(spinner)
+
+        # Should render the refresh button with the w-progress controller
+        refresh_button = controller.select_one("button")
+        self.assertIsNotNone(refresh_button)
+        self.assertEqual(refresh_button.get("data-controller"), "w-progress")
+        self.assertEqual(refresh_button.text.strip(), "Refresh")
+
     def test_show_preview_on_revisions_list(self):
         latest_revision = self.multiple.save_revision(log_action=True)
         history_url = self.get_url(self.multiple, "history", args=(self.multiple.pk,))