wagtail/docs/releases/5.0.md

Wagtail 5.0 release notes - IN DEVELOPMENT

Unreleased

---
local:
depth: 1
---

What's new

...

Other features

• Add WAGTAILIMAGES_EXTENSIONS setting to restrict image uploads to specific file types (Aman Pandey, Ananjan-R)
• Update user list column level to Access level to be easier to understand (Vallabh Tiwari)
• Migrate .button-longrunning behaviour to a Stimulus controller with support for custom label element & duration (Loveth Omokaro)
• Implement new simplified userbar designs (Albina Starykova)
• Add more Axe rules to the accessibility checker (Albina Starykova)
• Add usage view for pages (Sage Abdullah)
• Copy page form now updates the slug field dynamically with a slugified value on blur (Loveth Omokaro)
• Ensure selected collection is kept when navigating from documents or images listings to add multiple views & upon upload (Aman Pandey, Bojan Mihelac)

Bug fixes

• Ensure label_format on StructBlock gracefully handles missing variables (Aadi jindal)
• Adopt a no-JavaScript and more accessible solution for the 'Reset to default' switch to Gravatar when editing user profile (Loveth Omokaro)
• Ensure Site.get_site_root_paths works on cache backends that do not preserve Python objects (Jaap Roes)
• Ignore right clicks on side panel resizer (Sage Abdullah)
• Resize in the correct direction for RTL languages with the side panel resizer (Sage Abdullah)
• Fix image uploads on storage backends that require file pointer to be at the start of the file (Matt Westcott)
• Fix "Edit this page" missing from userbar (Satvik Vashisht)
• No longer allow invalid duplicate site hostname creation as hostnames and domain names are a case insensitive (Coen van der Kamp)
• Image and Document multiple upload update forms now correctly use the progress button (longrunning) behaviour when clicked (Loveth Omokaro)
• Prevent audit log report from failing on missing models (Andy Chosak)
• Ensure that the privacy collection privacy edit button is styled as a button (Jatin Kumar)

Documentation

• Add code block to make it easier to understand contribution docs (Suyash Singh)
• Add new "Icons" page for icons customisation and reuse across the admin interface (Coen van der Kamp)
• Fix broken formatting for MultiFieldPanel / FieldRowPanel permission kwarg docs (Matt Westcott)
• Add helpful troubleshooting links and refine wording for getting started with development (Loveth Omokaro)
• Ensure search autocomplete overlay on mobile does not overflow the viewport (Ayman Makroo)
• Improve documentation for InlinePanel (Vallabh Tiwari)
• Remove confusing SettingsPanel reference in the page editing TabbedInterface example as SettingsPanel no longer shows anything as of 4.1 (Kenny Wolf, Julian Bigler)

Maintenance

• Removed features deprecated in Wagtail 3.0 and 4.0 (Matt Westcott)
• Update djhtml (html formatting) library to v 1.5.2 (Loveth Omokaro)
• Re-enable strictPropertyInitialization in tsconfig (Thibaud Colas)
• Refactor accessibility checker userbar item (Albina Starykova)
• Removed unused Page.get_static_site_paths method (Yosr Karoui)
• Provisional Django 5.0 compatibility fixes (Sage Abdullah)
• Add unit tests for CollapseAll and MinimapItem components (Albina Starykova)
• Code quality fixes (GLEF1X)
• Refactor image / document / snippet usage views into a shared generic view (Sage Abdullah)
• Rename the Stimulus AutoFieldController to the less confusing SubmitController (Loveth Omokaro)
• Replace script tags with template tag for image/document bulk uploads (Rishabh Kumar Bahukhandi)
• Remove unneeded float styles on 404 page (Fabien Le Frapper)
• Convert userbar implementation to TypeScript (Albina Starykova)
• Migrate slug field behaviour to a Stimulus controller and create new SlugInput widget (Loveth Omokaro)
• Refactor status HTML usage to shared template tag (Aman Pandey, LB (Ben) Johnston)
• Add curlylint and update djhtml, semgrep versions in pre-commit config (Himanshu Garg)
• Use shared header template for ModelAdmin header (Aman Pandey)

Upgrade considerations

Removal of deprecated features

The following features deprecated in Wagtail 3.0 have been fully removed. See Wagtail 3.0 release notes for details on these changes, including how to remove usage of these features:

• The modules wagtail.core, wagtail.tests, wagtail.admin.edit_handlers and wagtail.contrib.forms.edit_handlers are removed.
• The field panel classes StreamFieldPanel, RichTextFieldPanel, ImageChooserPanel, DocumentChooserPanel and SnippetChooserPanel are removed.
• StreamField definitions must include use_json_field=True (with the exception of migrations created prior to Wagtail 5.0).
• The BASE_URL setting is no longer recognised.
• The ModelAdmin.get_form_fields_exclude method is no longer passed a request argument.
• The ModelAdmin.get_edit_handler method is no longer passed a request or instance argument.
• The widget_overrides, required_fields, required_formsets, bind_to, render_as_object and render_as_field methods on Panel (previously EditHandler) are removed.

The following features deprecated in Wagtail 4.0 have been fully removed. See Wagtail 4.0 release notes for details on these changes, including how to remove usage of these features:

• The wagtail.contrib.settings.models.BaseSetting class is removed.
• The Page.get_latest_revision_as_page method is removed.
• The page and page_id properties and as_page_object method on Revision are removed.
• The JavaScript functions createPageChooser, createSnippetChooser, createDocumentChooser and createImageChooser are removed.
• The wagtail.contrib.modeladmin.menus.SubMenu class is removed.
• Subclasses of wagtail.contrib.modeladmin.helpers.AdminURLHelper are now required to accept a base_url_path keyword argument on the constructor.
• The wagtail.admin.widgets.chooser.AdminChooser class is removed.
• The wagtail.snippets.views.snippets.get_snippet_edit_handler function is removed.

Page.get_static_site_paths method removed

The undocumented Page.get_static_site_paths method (which returns a generator of URL paths for use by static site generator packages) has been removed. Packages relying on this functionality should provide their own fallback implementation.

Changes to header CSS classes in ModelAdmin templates

If there are custom styles in place for the ModelAdmin's header content or more complex template overrides in us, there are a few changes for the following classes to be aware of.

Content	Old classes	New classes
Heading & search (contains h1)	.left.header-left	.left
Action buttons (header_extra)	.right.header-right	.right

Slug field widget required for auto-formatting

The slug field JavaScript behaviour was previously attached to any field with an ID of id_slug, this has now changed to be any field with the appropriate HTML data attributes.

If using a custom edit handler or set of panels for page models, the correct widget will now need to be used for these data attributes to be included. This widget will use the WAGTAIL_ALLOW_UNICODE_SLUGS Django setting.

from wagtail.admin.widgets.slug import SlugInput
# ... other imports

class MyPage(Page):
    promote_panels = [
        FieldPanel("slug", widget=SlugInput),
        # ... other panels
    ]

Additionally, the slug behaviour can be attached to any field easily by including the following attributes in HTML or via Django's widget attrs.

<input type="text" name="slug" data-controller="w-slug" data-action="blur->w-slug#slugify" />

To allow unicode values, add the data attribute value;

<input type="text" name="slug" data-controller="w-slug" data-action="blur->w-slug#slugify" data-w-slug-allow-unicode="true" />

Progress button (button-longrunning) now implemented with Stimulus

The button-longrunning class usage has been updated to use the newly adopted Stimulus approach, the previous data attributes will be deprecated in a future release.

If using the old approach, ensure any HTML templates are updated to the new approach before the next major release.

Old syntax

<button type="submit" class="button action-save button-longrunning" data-clicked-text="{% trans 'Creating…' %}">
  {% icon name="spinner" %}
  <em>{% trans 'Create' %}</em>
</button>

New syntax

Minimum required attributes are data-controller and a data-action.

<button type="submit" class="button action-save button-longrunning" data-controller="w-progress" data-action="w-progress#activate" data-w-progress-active-value="{% trans 'Creating…' %}">
  {% icon name="spinner" %}
  <em data-w-progress-target="label">{% trans 'Create' %}</em>
</button>

Examples of additional capabilities

Stimulus targets and actions can be leveraged to revise the behaviour via data attributes.

• <button ... data-w-progress-duration-value="500" ...> - custom duration can be declared on the element
• <button ... class="custom-button" data-w-progress-active-class="custom-button--busy" ...> - custom 'active' class to replace the default button-longrunning-active (must be a single string without spaces)
• <button ... ><strong data-w-progress-target="label">{% trans 'Create' %}</strong></button> - any element can be the button label (not just em)
• <button ... data-action="w-progress#activate focus->w-progress#activate" ...> - any event can be used to trigger the in progress behaviour
• <button ... data-action="w-progress#activate:once" ...> - only trigger the progress behaviour once
• <button ... data-action="readystatechange@document->w-progress#activate:once" data-w-progress-duration-value="5000" disabled ...> - disabled on load (once JS starts) and becomes enabled after 5s duration

Client-side BlockValidationError classes removed

The client-side handling of StreamField validation errors has been updated. The JavaScript classes StreamBlockValidationError, ListBlockValidationError, StructBlockValidationError and TypedTableBlockValidationError have been removed, and the corresponding Python classes can no longer be serialised using Telepath. Instead, the setError methods on client-side block objects now accept a plain JSON representation of the error, obtained from the as_json_data method on the Python class. Custom JavaScript code that works with these objects must be updated accordingly.