wagtail/docs/releases/5.2.md

Wagtail 5.2 release notes - IN DEVELOPMENT

Unreleased

---
local:
depth: 1
---

What's new

Other features

• Add wagtailcache and wagtailpagecache template tags to ensure previewing Pages or Snippets will not be cached (Jake Howard)
• Always set help text element ID for form fields with help text in field.html template (Sage Abdullah)
• Move SnippetViewSet menu registration mechanism to base ViewSet class (Sage Abdullah)
• Enable reference index tracking for models registered with ModelViewSet (Sage Abdullah)
• When copying a page or creating an alias, copy its view restrictions to the destination (Sandeep Choudhary, Suyash Singh)
• Support pickling of StreamField values (pySilver)
• Move SnippetViewSet template override mechanism to ModelViewSet (Sage Abdullah)
• Move SnippetViewSet.list_display to ModelViewSet (Sage Abdullah)
• Remove wagtail.publish log action on aliases when they are created from live source pages or the source page is published (Dan Braghis)
• Remove wagtail.unpublish log action on aliases when source page is unpublished (Dan Braghis)
• Add compare buttons to workflow dashboard panel (Matt Westcott)
• Add the ability to use filters and to export listings in generic IndexView (Sage Abdullah)
• Move list_filter, filterset_class, search_fields, search_backend_name, list_export, export_filename, list_per_page, and ordering from SnippetViewSet to ModelViewSet (Sage Abdullah)
• Add default header titles to generic IndexView and CreateView (Sage Abdullah)
• Allow overriding IndexView.export_headings via ModelViewSet (Christer Jensen, Sage Abdullah)
• Support specifying a get_object_list method on ChooserViewSet (Matt Westcott)
• Add linked_fields mechanism on chooser widgets to allow choices to be limited by fields on the calling page (Matt Westcott)
• Add support for merging cells within TableBlock with the mergedCells option (Gareth Palmer)
• When adding a panel within InlinePanel, focus will now shift to that content similar to StreamField (Faishal Manzar)

Bug fixes

• Ensure that StreamField's FieldBlocks correctly set the required and aria-describedby attributes (Storm Heg)
• Avoid an error when the moderation panel (admin dashboard) contains both snippets and private pages (Matt Westcott)
• When deleting collections, ensure the collection name is correctly shown in the success message (LB (Ben) Johnston)
• Filter out comments on Page editing counts that do not correspond to a valid field / block path on the page such as when a field has been removed (Matt Westcott)

Documentation

• Document WAGTAILADMIN_BASE_URL on "Integrating Wagtail into a Django project" page (Shreshth Srivastava)
• Replace incorrect screenshot for authors listing on tutorial (Shreshth Srivastava)
• Add documentation for building non-model-based choosers using the queryish library (Matt Westcott)
• Fix incorrect tag library import on focal points example (Hatim Makki Hoho)

Maintenance

• Fix snippet search test to work on non-fallback database backends (Matt Westcott)
• Update Eslint, Prettier & Jest npm packages (LB (Ben) Johnston)
• Add npm scripts for TypeScript checks and formatting SCSS files (LB (Ben) Johnston)
• Run tests in parallel in some of the CI setup (Sage Abdullah)
• Remove unused WorkflowStatus view, urlpattern, and workflow-status.js (Storm Heg)
• Add support for options/attrs in Telepath widgets so that attrs render on the created DOM (Storm Heg)
• Update pre-commit hooks to be in sync with latest changes to Eslint & Prettier for client-side changes (Storm Heg)
• Add WagtailTestUtils.get_soup() method for testing HTML content (Storm Heg, Sage Abdullah)
• Allow ViewSet subclasses to customise url_prefix and url_namespace logic (Matt Westcott)
• Simplify SnippetViewSet registration code (Sage Abdullah)
• Rename groups IndexView.results_template_name to results.html (Sage Abdullah)
• Migrate form submission listing checkbox toggling to the shared w-bulk Stimulus implementation (LB (Ben) Johnston)
• Allow viewsets to define a common set of view kwargs (Matt Westcott)
• Migrate the editor unsaved messages popup to be driven by Stimulus using the shared w-message controller (LB (Ben) Johnston, Hussain Saherwala)
• Add support for tooltip position in human_readable_date tooltip (Rohit Sharma)

Upgrade considerations - changes affecting all projects

Upgrade considerations - deprecation of old functionality

Upgrade considerations - changes affecting Wagtail customisations

ModelViewSet automatically registers the model to the reference index

Models that are registered with a ModelViewSet now have reference index tracking enabled by default. This means that you no longer need to call ReferenceIndex.register_model() in your app's ready() method for such models. If this is undesired, you can disable it by setting {attr}~wagtail.admin.viewsets.model.ModelViewSet.add_to_reference_index to False on the ModelViewSet subclass. For more details, see .

Groups IndexView.results_template_name renamed from results.html to index_results.html

The IndexView's results_template_name attribute in the GroupViewSet has been renamed from wagtailusers/groups/results.html to wagtailusers/groups/index_results.html for consistency with the other viewsets. If you have customised or extended the template, e.g. for , you will need to rename it to match the new name.

Breadcrumbs class name has changed

If using custom styling for the breadcrumbs, this class has changed from singular to plural for a more intuitive class.

Old	New
'w-breadcrumb'	'w-breadcrumbs'

Breadcrumbs now use different data attributes and events

The undocumented JavaScript implementation for the header breadcrumbs component has been migrated to a Stimulus controller and now uses different data attributes.

This may impact custom header implementations that relied on the previous approach, custom breadcrumbs that did not use breadcrumbs and require the expand/collapse behaviour may be impacted.

Events

Old	New
'wagtail:breadcrumbs-expand'	'w-breadcrumbs:opened'
'wagtail:breadcrumbs-collapse'	'w-breadcrumbs:closed'

Data attributes

Old	New
data-breadcrumb-next	data-controller="w-breadcrumbs"
data-toggle-breadcrumbs	data-w-breadcrumbs-target="toggle" data-action="w-breadcrumbs#toggle mouseenter->w-breadcrumbs#peek"
data-breadcrumb-item	data-w-breadcrumbs-target="content"

Note that the root DOM element also includes a set of additional data attributes to function as the breadcrumbs:

data-controller="w-breadcrumbs"
data-action="keyup.esc@document->w-breadcrumbs#close w-breadcrumbs:open@document->w-breadcrumbs#open w-breadcrumbs:close@document->w-breadcrumbs#close"
data-w-breadcrumbs-close-icon-class="icon-cross"
data-w-breadcrumbs-closed-value="true"
data-w-breadcrumbs-open-icon-class="icon-breadcrumb-expand"
data-w-breadcrumbs-opened-content-class="w-max-w-4xl"
data-w-breadcrumbs-peek-target-value="header"

window.updateFooterSaveWarning global util removed

The undocumented global util window.updateFooterSaveWarning has been removed, this is part of the footer 'unsaved' messages toggling behaviour on page forms. This behaviour has now moved to a Stimulus controller and leverages DOM events instead. Calling this function will do nothing and in a future release will throw an error.

You can implement roughly the equivalent functionality with this JavaScript function, however, this will not be guaranteed to work in future releases.

window.updateFooterSaveWarning = (formDirty, commentsDirty) => {
  if (!formDirty && !commentsDirty) {
    document.dispatchEvent(new CustomEvent('w-unsaved:clear'));
  } else {
    const [type] = [
      formDirty && commentsDirty && 'all',
      commentsDirty && 'comments',
      formDirty && 'edits',
    ].filter(Boolean);
    document.dispatchEvent(new CustomEvent('w-unsaved:add', { detail: { type } }));
  }
};