Release note / upgrade consideration for TitlefieldPanel #10568

CHANGELOG.txt

@@ -47,6 +47,7 @@ Changelog
 5.0.2 (xx.xx.xxxx) - IN DEVELOPMENT
 ~~~~~~~~~~~~~~~~~~
 
+ * Added `TitleFieldPanel` to support title / slug field synchronisation (LB (Ben) Johnston)
  * Fix: Prevent JS error when reverting the spinner on a submit button after a validation error (LB (Ben) Johnston)
  * Fix: Prevent crash when comparing page revisions that include `MultipleChooserPanel` (Matt Westcott)
  * Fix: Ensure that title and slug continue syncing after entering non-URL-safe characters (LB (Ben) Johnston)

docs/reference/pages/panels.md

@@ -228,6 +228,7 @@ The `MultipleChooserPanel` definition on `BlogPage` would be:
 
 ```{eval-rst}
 .. module:: wagtail.admin.panels
+   :noindex:
 
 .. autoclass:: TitleFieldPanel
 

docs/releases/5.0.2.md

@@ -11,6 +11,10 @@ depth: 1
 
 ## What's new
 
+### New features
+
+ * Added [](title_field_panel) to support title / slug field synchronisation (LB (Ben) Johnston)
+
 ### Bug fixes
 
  * Prevent JS error when reverting the spinner on a submit button after a validation error (LB (Ben) Johnston)
@@ -18,3 +22,37 @@ depth: 1
  * Ensure that title and slug continue syncing after entering non-URL-safe characters (LB (Ben) Johnston)
  * Ensure that title and slug are synced on keypress, not just on blur (LB (Ben) Johnston)
  * Add a more visible active state for side panel toggle buttons (Thibaud Colas)
+
+## Upgrade considerations
+
+### Use of `TitleFieldPanel` for the page title field
+
+This release introduces a new [](title_field_panel) class, which is used by default for the page title field and provides the mechanism for synchronising the slug field with the title. Prior to Wagtail 5.0, this happened automatically on any field named 'title'.
+
+If you have used `FieldPanel("title")` directly in a panel definition (rather than extending `Page.content_panels` as standard), and wish to restore the previous behaviour of auto-populating the slug, you will need to change this to `TitleFieldPanel("title")`. For example:
+
+```python
+from wagtail.admin.panels import FieldPanel, MultiFieldPanel
+
+    # ...
+    content_panels = [
+        MultiFieldPanel([
+            FieldPanel("title"),
+            FieldPanel("subtitle"),
+        ]),
+    ]
+```
+
+should become:
+
+```python
+from wagtail.admin.panels import FieldPanel, MultiFieldPanel, TitleFieldPanel
+
+    # ...
+    content_panels = [
+        MultiFieldPanel([
+            TitleFieldPanel("title"),
+            FieldPanel("subtitle"),
+        ]),
+    ]
+```

docs/releases/5.0.md

@@ -341,11 +341,41 @@ To allow unicode values, add the data attribute value;
 />
 ```
 
-### Title field auto sync with the slug field on Pages now relies on data attributes
+### Changes to title / slug field synchronisation
 
-The title field will sync its value with the slug field on Pages if the Page is not published and the slug has not been manually changed. This JavaScript behaviour previously attached to any field with an ID of `id_title`, this has now changed to be any field with the appropriate Stimulus data attributes.
+The mechanism for synchronising the slug field with the page title has changed, and is no longer hard-coded to activate on fields named 'title'. Notably, this change affects page panel definitions that use `FieldPanel("title")` directly (rather than the convention of extending `Page.content_panels`), as well as non-page models such as snippets.
 
-If your project is using the built in `title` and `slug` fields without any customisations, you will not need to do anything differently. However, if you were relying on this behaviour or the `window.initSlugAutoPopulate` global, please read ahead as you may need to make some changes to adopt the new approach.
+To assist in upgrading these definitions, Wagtail 5.0.2 provides a new [](title_field_panel) class to be used in place of `FieldPanel("title")`. For example:
+
+```python
+from wagtail.admin.panels import FieldPanel, MultiFieldPanel
+
+    # ...
+    content_panels = [
+        MultiFieldPanel([
+            FieldPanel("title"),
+            FieldPanel("subtitle"),
+        ]),
+    ]
+```
+
+should become:
+
+```python
+from wagtail.admin.panels import FieldPanel, MultiFieldPanel, TitleFieldPanel
+
+    # ...
+    content_panels = [
+        MultiFieldPanel([
+            TitleFieldPanel("title"),
+            FieldPanel("subtitle"),
+        ]),
+    ]
+```
+
+If you have made deeper customisations to this behaviour, or are unable to upgrade to Wagtail 5.0.2 or above, please read on as you may need to make some changes to adopt the new approach.
+
+The title field will sync its value with the slug field on Pages if the Page is not published and the slug has not been manually changed. This JavaScript behaviour previously attached to any field with an ID of `id_title`; this has now changed to be any field with the appropriate Stimulus data attributes.
 
 There is a new Stimulus controller `w-sync` which allows any field to change one or more other fields when its value changes, the other field in this case will be the slug field (`w-slug`) with the id `id_slug`.