From 4dd99007f61969249dc19f83cc09e15e621d7d2d Mon Sep 17 00:00:00 2001 From: Matt Westcott Date: Tue, 20 Jun 2023 13:03:03 +0100 Subject: [PATCH] Release note / upgrade consideration for TitlefieldPanel #10568 --- CHANGELOG.txt | 1 + docs/reference/pages/panels.md | 1 + docs/releases/5.0.2.md | 38 ++++++++++++++++++++++++++++++++++ docs/releases/5.0.md | 36 +++++++++++++++++++++++++++++--- 4 files changed, 73 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.txt b/CHANGELOG.txt index 64710d7d4d..cb944ddf0b 100644 --- a/CHANGELOG.txt +++ b/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) diff --git a/docs/reference/pages/panels.md b/docs/reference/pages/panels.md index a295225a6c..8da2a9352c 100644 --- a/docs/reference/pages/panels.md +++ b/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 diff --git a/docs/releases/5.0.2.md b/docs/releases/5.0.2.md index 64bb7eb06a..089d201f81 100644 --- a/docs/releases/5.0.2.md +++ b/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"), + ]), + ] +``` diff --git a/docs/releases/5.0.md b/docs/releases/5.0.md index 1d7afe42d8..d7bf5461ef 100644 --- a/docs/releases/5.0.md +++ b/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`.