wagtail/docs/releases/5.2.md

# Wagtail 5.2 release notes - IN DEVELOPMENT

_Unreleased_

```{contents}
---
local:
depth: 1
---
```

## What's new


### Other features

 * Add [`wagtailcache`](wagtailcache) and [`wagtailpagecache`](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](table_block_options) (Gareth Palmer)
 * When adding a panel within `InlinePanel`, focus will now shift to that content similar to `StreamField` (Faishal Manzar)
 * Show the full first published at date within a tooltip on the Page status sidebar on the relative date (Rohit Sharma)
 * Extract generic breadcrumbs functionality from page breadcrumbs (Sage Abdullah)
 * Add support for `placement` in `human_readable_date` the tooltip template tag (Rohit Sharma)
 * Add breadcrumbs to generic model views (Sage Abdullah)

### Bug fixes

 * Ensure that StreamField's `FieldBlock`s 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)
 * Allow `PublishMenuItem` to more easily support overriding its label via `construct_page_action_menu` (Sébastien Corbin)

### 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)
 * Do not use jest inside `stubs.js` to prevent Storybook from crashing (LB (Ben) Johnston)
 * Refactor snippets templates to reuse the shared `slim_header.html` template (Sage Abdullah)
 * Refactor `slim_header.html` template to reduce code duplication (Sage Abdullah)
 * Upgrade Willow to v1.6.2 to support MIME type data without reliance on `imghdr` (Jake Howard)
 * Replace `imghdr` with Willow's built-in MIME type detection (Jake Howard)
 * Migrate all other `data-tippy` HTML attribute usage to the Stimulus data-*-value attributes for w-tooltip & w-dropdown (Subhajit Ghosh, LB (Ben) Johnston)
 * Replace `@total_ordering` usage with comparison functions implementation (Virag Jain)


## Upgrade considerations - changes affecting all projects

### Removal of `imghdr` and upgrade to `Willow`

[`imghdr`](https://docs.python.org/3/library/imghdr.html) is deprecated, and will be removed in Python 3.13.

Wagtail now uses the Willow feature of providing the image MIME type, which uses the [`filetype`](https://pypi.org/project/filetype/) package.

## 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 [](managing_the_reference_index).

### 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 [](customising_group_views), 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.

```js
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 } }));
  }
};
```

### Snippets templates refactored to reuse the shared `slim_header.html` template

The templates for the snippets views have been refactored to reuse the shared `slim_header.html` template. If you have customised or extended the templates, e.g. for [](wagtailsnippets_custom_admin_views), you will need to update them to match the new structure. As a result, the following templates have been removed:

- `wagtailsnippets/snippets/headers/_base_header.html`
- `wagtailsnippets/snippets/headers/create_header.html`
- `wagtailsnippets/snippets/headers/history_header.html`
- `wagtailsnippets/snippets/headers/list_header.html`
- `wagtailsnippets/snippets/headers/usage_header.html`

In most cases, the usage of those templates can be replaced with the `wagtailadmin/shared/headers/slim_header.html` template. Refer to the snippets views and templates code for more details.

### `dropdown` template tag argument `toggle_tippy_offset` renamed to `toggle_tooltip_offset`

The naming conventions for `tippy` related attributes have been updated to align with the generic `tooltip` naming.

If you are using the undocumented dropdown template tag with the offset arg, this will need to be updated.

| Old                                                                | New                                                                  |
| ------------------------------------------------------------------ | -------------------------------------------------------------------- |
| `{% dropdown toggle_tippy_offset="[0, -2]" %}...{% enddropdown %}` | `{% dropdown toggle_tooltip_offset="[0, -2]" %}...{% enddropdown %}` |