wagtail/docs/releases/5.2.md

Wagtail 5.2 release notes - IN DEVELOPMENT

Unreleased

---
local:
depth: 1
---

What's new

OpenSearch support

OpenSearch is now formally supported as an alternative to Elasticsearch. For configuration details, see OpenSearch configuration. This feature was developed by Matt Westcott.

Other features

• Add support for Python 3.12 (Matt Westcott)
• 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)
• 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)
• Extract generic HistoryView from snippets and add it to ModelViewSet (Sage Abdullah)
• Add generic UsageView to ModelViewSet (Sage Abdullah)
• Add the ability to define listing buttons on generic IndexView (Sage Abdullah)
• Add a visual progress bar to the output of the wagtail_update_image_renditions management command (Faishal Manzar)
• Increase the read buffer size to improve efficiency and performance when generating file hashes for document or image uploads, use hashlib.file_digest if available (Python 3.11+) (Jake Howard)
• API ordering now supports multiple fields (Rohit Sharma, Jake Howard)

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)
• 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)
• Update Spotify oEmbed provider URL parsing to resolve correctly (Dhrűv)
• Update link colours within help blocks to meet accessible contrast requirements (Rohit Sharma)
• Ensure the search promotions popular search terms picker correctly refers to the correct model (LB (Ben) Johnston)
• Correctly quote non-numeric primary keys on snippet inspect view (Sage Abdullah)
• Prevent crash on snippet inspect view when displaying a null foreign key to an image (Sage Abdullah)
• Ensure that pages in moderation show as "Live + In Moderation" in the page explorer rather than "Live + Draft" (Sage Abdullah)
• Prevent error when updating reference index for objects with a lazy ParentalKey-related object (Chris Shaw)
• Ignore conflicts when inserting reference index entries to prevent race conditions causing uniqueness errors (Chris Shaw)

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)
• Add reminder about including your custom Draftail feature in any overridden WAGTAILADMIN_RICH_TEXT_EDITORS setting (Charlie Sue)
• Mention the need to install python3-venv on Ubuntu (Brian Mugo)
• Document the use of the Google developer documentation style guide in documentation (Damilola Oladele)
• Fix Inconsistent URL Format in Getting Started tutorial (Olumide Micheal)
• Add more extensive documentation for the permission kwarg support in Panels (LB (Ben) Johnston)

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)
• Optimise lru_cache usage (Jake Howard)
• Implement date_since in get_most_popular inside search_promotions.models.Query (TopDevPros)
• Refactor generic view subclasses to better reuse the generic templates and breadcrumbs (Sage Abdullah)
• Adopt consistent classname (not classnames) attributes for all MenuItem usage, including deprecation warnings (LB (Ben) Johnston)
• Adopt consistent classname (not classnames) attribute within the wagtail.images.formats.Format instance, including deprecation warnings (LB (Ben) Johnston)
• Deprecate context argument of construct_snippet_listing_buttons hook (Sage Abdullah)
• Deprecate legacy moderation system (Sage Abdullah)
• Update CI database versions (Jake Howard)
• Add changelog and issue tracker links to the PyPI project page (Panagiotis H.M. Issaris)
• Add better deprecation warnings to the search.Query & search.QueryDailyHits model, move final set of templates from the admin search module to the search promotions contrib module (LB (Ben) Johnston)
• Add generic InspectView to ModelViewSet (Sage Abdullah)
• Migrate select all on focus/click behavior to Stimulus, used on the image URL generator (Chiemezuo Akujobi)

Upgrade considerations - changes affecting all projects

Removal of imghdr and upgrade to Willow

imghdr 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 package.

Adoption of classname convention for MenuItem related classes and hooks

Wagtail MenuItem and menu hooks have been updated to use the more consistent naming of classname (singular) instead of classnames (plural), a convention that started in Wagtail 4.2.

The current classnames keyword argument naming will be supported, but will trigger a deprecation warning. Support for this variant will be removed in a future release.

The following classes will adopt this new convention.

• admin.menu.MenuItem
• admin.ui.sidebar.ActionMenuItem
• admin.ui.sidebar.LinkMenuItem
• admin.ui.sidebar.PageExplorerMenuItem
• contrib.settings.registry.SettingMenuItem

The following hooks usage may be impacted if classnames were used when generating menu items.

• register_admin_menu_item
• register_settings_menu_item

Example

from django.urls import reverse

from wagtail import hooks
from wagtail.admin.menu import MenuItem

@hooks.register('register_admin_menu_item')
def register_frank_menu_item():
  return MenuItem(
    'Frank',
    reverse('frank'),
    icon_name='folder-inverse',
    order=10000,
    classname="highlight-menu" # not classnames=...
  )

Upgrade considerations - deprecation of old functionality

Legacy moderation system is deprecated

The legacy moderation system, which was replaced by the new workflow system in Wagtail 2.10, is now deprecated. Since Wagtail 2.10, submitting a page for moderation will use the new workflow system. However, the legacy moderation system is still in place for approving and rejecting pages that were submitted for moderation before Wagtail 2.10.

To view all pages that are still in the legacy moderation system backlog, you can sign in as a superuser and see if there is a "Pages awaiting moderation" section in the admin dashboard. You can approve or reject the pages from there. You can also do this programmatically by querying for Revision.objects.filter(submitted_for_moderation=True) and calling revision.approve_moderation() or revision.reject_moderation() on each revision.

The legacy moderation system will be removed in a future release. If you still have pages in the moderation queue that were submitted for moderation before Wagtail 2.10, you should approve or reject them before upgrading. See for more details.

As a result, the following features are now deprecated:

• {attr}wagtail.models.Revision.submitted_for_moderation
• {attr}wagtail.models.Revision.submitted_revisions
• {meth}wagtail.models.Revision.approve_moderation
• {meth}wagtail.models.Revision.reject_moderation
• The submitted_for_moderation argument in {meth}wagtail.models.RevisionMixin.save_revision
• WAGTAIL_MODERATION_ENABLED
• wagtail.admin.userbar.ModeratePageItem
• wagtail.admin.userbar.ApproveModerationEditPageItem
• wagtail.admin.userbar.RejectModerationEditPageItem
• wagtail.admin.views.home.PagesForModerationPanel
• wagtail.admin.views.pages.moderation
• wagtail.permission_policies.pages.PagePermissionPolicy.revisions_for_moderation

If you use any of the above features, remove them or replace them with the equivalent features from the new workflow system. The above features will be removed in a future release.

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 .

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'

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 , 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/edit_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.

BaseSidePanels, PageSidePanels and SnippetSidePanels classes are removed

The BaseSidePanels, PageSidePanels and SnippetSidePanels classes that were used to combine the side panels (i.e. status, preview and comments side panels) have been removed. Each side panel is now instantiated directly in the view. The wagtail.admin.ui.components.MediaContainer class can be used to combine the Media objects for the side panels.

The BasePreviewSidePanel, PagePreviewSidePanel and SnippetPreviewSidePanel classes have been replaced with the consolidated PreviewSidePanel class.

The BaseStatusSidePanel class has been renamed to StatusSidePanel.

If you use these classes in your code, you will need to update your code to instantiate the side panels directly in the view.

For example, if you have the following code:

from wagtail.admin.ui.side_panels import PageSidePanels


def my_view(request):
    ...

    side_panels = PageSidePanels(
        request,
        page.get_latest_revision_as_object(),
        show_schedule_publishing_toggle=False,
        live_page=page,
        scheduled_page=page.get_scheduled_revision_as_object(),
        in_explorer=False,
        preview_enabled=True,
        comments_enabled=False,
    )

    return render(
        request,
        template_name,
        {"page": page, "side_panels": side_panels, "media": side_panels.media},
    )

Update it to the following:

from wagtail.admin.ui.components import MediaContainer
from wagtail.admin.ui.side_panels import PageStatusSidePanel, PreviewSidePanel


def my_view(request):
    ...

    side_panels = [
        PageStatusSidePanel(
            page,
            request,
            show_schedule_publishing_toggle=False,
            live_object=page,
            scheduled_object=page.get_scheduled_revision_as_object(),
            locale=page.locale,
            translations=translations,
        ),
        PreviewSidePanel(
            page,
            request,
            preview_url=reverse("wagtailadmin_pages:preview_on_edit", args=[page.id]),
        ),
    ]
    side_panels = MediaContainer(side_panels)

    return render(
        request,
        template_name,
        {"page": page, "side_panels": side_panels, "media": side_panels.media},
    )

construct_snippet_listing_buttons hook no longer accepts a context argument

The construct_snippet_listing_buttons hook no longer accepts a context argument. If you have implemented this hook, you will need to remove the context argument from your implementation. If you need to access values computed by the view, you'll need to override the {attr}~wagtail.snippets.views.snippets.SnippetViewSet.index_view_class with a custom IndexView subclass. The get_list_buttons and get_list_more_buttons methods in particular may be overridden to customise the buttons on the listing.

Defining a function for this hook that accepts the context argument will raise a warning, and the function will receive an empty dictionary ({}) as the context. Support for defining the context argument will be completely removed in a future Wagtail release.

Upgrade considerations - changes to undocumented internals

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

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

{% 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 element to avoid content from being parsed by the browser on load.

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

Adoption of classname convention within the Image Format instance

When using wagtail.images.formats.Format, the created instance set the argument for classes to the attribute classnames (plural), this has now changed to classname (singular).

For any custom code that accessed or modified this undocumented attribute, updates will need to be made as follows.

Accessing self.classnames will still work until a future release, simply returning self.classname, but this will raise a deprecation warning.

# image_formats.py
from django.utils.html import format_html
from wagtail.images.formats import Format, register_image_format


class CustomImageFormat(Format):

    def image_to_html(self, image, alt_text, extra_attributes=None):
        # contrived example - pull out the class and render on outside element
        classname = self.classname # not self.classnames
        self.classname = "" # not self.classnames
        inner_html = super().image_to_html(image, alt_text, extra_attributes)
        return format_html("<custom-image class='{}'>{}</custom-image>", classname, inner_html)


custom_format = CustomImageFormat('custom_example', 'Custom example', 'example-image object-fit', 'width-750')

register_image_format(custom_format)

Changes to search promotions contrib module

Deprecated search_garbage_collect management command has been removed

In 5.0 the documentation advised that the search_garbage_collect command used to remove old stored search queries and daily hits has been moved to searchpromotions_garbage_collect.

The old command has now been fully removed and if called will throw an error.

Changes to URL names and templates

Some search promotions URLs and templates have now moved from the main admin search module into the search promotions module.

Item	Old	New
URL name	wagtailsearch_admin:queries_chooser	wagtailsearchpromotions:chooser
URL name	wagtailsearch_admin:queries_chooserresults	wagtailsearchpromotions:queries_chooserresults
Template	wagtail/search/templates/wagtailsearch/queries/chooser/chooser.html	wagtail/contrib/search_promotions/templates/wagtailsearchpromotions/queries/chooser/chooser.html
Template	wagtail/search/templates/wagtailsearch/queries/chooser/results.html	wagtail/contrib/search_promotions/templates/wagtailsearchpromotions/queries/chooser/results.html
Template	wagtail/search/templates/wagtailsearch/queries/chooser_field.html	wagtail/contrib/search_promotions/templates/wagtailsearchpromotions/queries/chooser_field.html