# Wagtail 5.2 release notes - IN DEVELOPMENT

_Unreleased_

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

## What's new

### OpenSearch support

[OpenSearch](https://opensearch.org/) is now formally supported as an alternative to Elasticsearch. For configuration details, see [OpenSearch configuration](opensearch). This feature was developed by Matt Westcott.

### 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)
 * Support passing extra context variables via the `{% component %}` tag (Matt Westcott)
 * Allow subclasses of `PagesAPIViewSet` override default Page model via the `model` attribute (Neeraj Yetheendran, Herbert Poul)
 * Allow `ModelViewSet` to be used with models that have non-integer primary keys (Sage Abdullah)
 * Add the ability to set an external link/text for promoted search result entries (TopDevPros, Brad Busenius)
 * Add support for subject and body in the Email link chooser form (TopDevPros, Alexandre Joly)

### 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)
 * Allow locale selection when creating a page at the root level (Sage Abdullah)
 * Ensure the admin login template correctly displays all `non_fields_errors` for any custom form validation (Sébastien Corbin)
 * Ensure 'mark as active' label in workflow bulk action set active form can be translated (Rohit Sharma)
 * Ensure the panel title for a user's settings correctly reflects the `WAGTAIL_EMAIL_MANAGEMENT_ENABLED` setting by not showing 'email' if disabled (Omkar Jadhav)

### 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)
 * Replace `<script type="text/django-form-template"><-/script>` template approach with HTML `template` elements in InlinePanel and expanding formset (Mansi Gundre, Subhajit Ghosh, LB (Ben) Johnston)
 * Refactor side panels code for better reuse in pages and snippets (Sage Abdullah)
 * Deprecate legacy URL redirects in `ModelViewSet` and `SnippetViewSet` (Sage Abdullah)
 * Simplify code for registering page listing action buttons (Matt Westcott)
 * Removed the unused, legacy, Wagtail userbar views set up for an old iframe approach (Sage Abdullah)


## 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

### Edit and delete URLs in `ModelViewSet` changed to allow non-integer primary keys

To accommodate models with non-integer primary keys, the URL patterns for the edit and delete views in {class}`~wagtail.admin.viewsets.model.ModelViewSet` have been changed.

Relative to the viewset's {attr}`~wagtail.admin.viewsets.base.ViewSet.url_prefix`, the following changes have been made:
- The edit URL pattern has been changed from `<int:pk>/` to `edit/<str:pk>/`
- The delete URL pattern has been changed from `<int:pk>/delete/` to `delete/<str:pk>/`

If you use {func}`~django.urls.reverse` with {meth}`~wagtail.admin.viewsets.base.ViewSet.get_url_name` to generate the URLs for these views, no changes are needed. However, if you have hard-coded these URLs in your code, you will need to update them to match the new patterns.

Redirects for the legacy URLs are in place for backwards compatibility, but will be removed in a future release.

The URLs for snippets underwent similar changes in Wagtail 2.14. The redirects for the legacy URLs in {class}`~wagtail.snippets.views.snippets.SnippetViewSet` have now been marked for removal in a future release.

### `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 %}` |

### `escapescript` template tag and `escape_script` functions are deprecated

As of this release, the undocumented `coreutils.escape_script` util and `escapescript` template tag will no longer be supported.

This was used to provide a way for HTML template content in IE11, which is no longer supported, and was non-compliant with CSP support.

The current approach will trigger a deprecation warning and will be removed in a future release.

#### Old

```html+django
{% load wagtailadmin_tags %}
<script type="text/django-form-template" id="id_{{ formset.prefix }}-EMPTY_FORM_TEMPLATE">
    {% escapescript %}
        <div>Widget template content</div>
        <script src="/js/my-widget.js"></script>
    {% endescapescript %}
</script>
```

#### New

Use the HTML [`template`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/template) element to avoid content from being parsed by the browser on load.

```html+django
<template id="id_{{ formset.prefix }}-EMPTY_FORM_TEMPLATE">
    <div>Widget template content</div>
    <script src="/js/my-widget.js"></script>
</template>
```