Wagtail 5.0 release notes - IN DEVELOPMENT

Unreleased

---
local:
depth: 1
---

What's new

Object usage information on deleting objects

On deleting a page, image, document or snippet, the confirmation screen now provides a summary of where the object is used, allowing users to see the effect that deletion will have elsewhere on the site. This also prevents objects from being deleted in cases where deletion would be blocked by an on_delete=PROTECT constraint. This feature was developed by Sage Abdullah.

SVG image support

The image library can now be configured to allow uploading SVG images. These are handled by the {% image %} template tag as normal, with some limitations on image operations - for full details, see [](svg_images). This feature was developed by Joshua Munn.

Custom validation support for StreamField

Support for adding custom validation logic to StreamField blocks has been formalised and simplified. For most purposes, raising a ValidationError from the block's clean method is now sufficient; more complex behaviours (such as attaching errors to a specific child block) are possible through block-specific subclasses of ValidationError. For more details, see [](streamfield_validation). This feature was developed by Matt Westcott.

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)
Sort accessibility checker results by position on the page (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)
Keep applied filters when downloading form submissions (Suyash Srivastava)
Messages added dynamically via JavaScript now have an icon to be consistent with those supplied in the page's HTML (Aman Pandey)
Switch lock/unlock side panel toggle to a switch, with more appropriate confirmation message status (Sage Abdullah)
Ensure that changed or cleared selection from choosers will dispatch a DOM change event (George Sakkis)
Add the ability to disable model indexing by setting search_fields = [] (Daniel Kirkham)
Enhance wagtail.search.utils.parse_query_string to allow inner single quotes for key/value parsing (Aman Pandey)
Add helpful properties to Locale for more convenient usage within templates, see [](i18n_basic_example) (Andy Babic)
Allow customising icons for snippets via SnippetViewSet.icon (Daniel Kirkham, Sage Abdullah)
Allow customising the base URL and URL namespace for snippet views (Sage Abdullah)
Allow customising the number of items per page for snippet listing views (Sage Abdullah)
Re-label "StreamField blocks" option in block picker to "Blocks" (Thibaud Colas)
Re-implement styleguide icons list as an auto-generated sequence of tables (Thibaud Colas)
Switch styleguide navigation to use panel components and minimap (Thibaud Colas)
Explicitly specify MenuItem.name for Snippets, Reports, and Settings menu items (Sage Abdullah)
Move the help text of fields and blocks directly below their label for easier reading (Thibaud Colas)

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)
Fix page/snippet cannot proceed a GroupApprovalTask if it's locked by someone outside of the group (Sage Abdullah)
Allow manual lock even if WorkflowLock is currently applied (Sage Abdullah)
Add missing log information for wagtail.schedule.cancel (Stefan Hammer)
Fix timezone activation leaking into subsequent requests in require_admin_access() (Stefan Hammer)
Fix dialog component's message to have rounded corners at the top side (Sam)
When multiple documents are uploaded and then subsequently updated, ensure that existing success messages are cleared correctly (Aman Pandey)
Prevent matches from unrelated models from leaking into SQLite FTS searches (Matt Westcott)
Prevent duplicate addition of StreamField blocks with the new block picker (Deepam Priyadarshi)
Enable partial search on images and documents index view where available (Mng)
Adopt a no-JavaScript and more accessible solution for option selection in reporting, using HTML only radio input fields (Mehul Aggarwal)
Ensure that document search results count shows the correct all matches, not the paginate total (Andy Chosak)
Fix radio and checkbox elements shrinking when using a long label (Sage Abdullah)
Fix select elements expanding beyond their container when using a long option label (Sage Abdullah)
Fix timezone handling of TemplateResponses for users with a custom timezone (Stefan Hammer, Sage Abdullah)
Ensure TableBlock initialisation correctly runs after load and its width is aligned with the parent panel (Dan Braghis)
Ensure that the JavaScript media files are loaded by default in Snippet index listings for date fields (Sage Abdullah)
Fix server-side caching of the icons sprite (Thibaud Colas)
Avoid showing scrollbars in the block picker unless necessary (Babitha Kumari)
Always show Add buttons, guide lines, Move up/down, Duplicate, Delete; in StreamField and Inline Panel (Thibaud Colas)
Make admin JS i18n endpoint accessible to non-authenticated users (Matt Westcott)

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, Thibaud Colas)
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)
Add contributor guidelines for building Stimulus Controllers (Thibaud Colas, Loveth Omokaro, LB (Ben) Johnston)
Fix typo in "Extending Draftail" documentation (Hans Kelson)
Clarify ClusterableModel requirements for using relations with RevisionMixin-enabled models (Sage Abdullah)

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, Himanshu Garg)
Add curlylint and update djhtml, semgrep versions in pre-commit config (Himanshu Garg)
Use shared header template for ModelAdmin and Snippets type index header (Aman Pandey)
Move models and forms for wagtailsearch.Query to wagtail.contrib.search_promotions (Karl Hobley)
Migrate initErrorDetection (tabs error counts) to a Stimulus Controller w-count (Aman Pandey)
Migrate window.addMessage behaviour to a global event listener & Stimulus Controller approach with w-messages (Aman Pandey)
Update Algolia DocSearch to use new application and correct versioning setup (Thibaud Colas)
Move snippet choosers and model check registration to SnippetViewSet.on_register() (Sage Abdullah)
Remove unused snippets delete-multiple view (Sage Abdullah)
Improve performance of determining live page URLs across the admin interface using pageurl template tag (Satvik Vashisht)
Migrate window.initSlugAutoPopulate behaviour to a Stimulus Controller w-sync (Loveth Omokaro)
Rename status classes to w-status to align with preferred CSS class naming conventions (Mansi Gundre)
Remove unused icon-help and help-inverse code (Thibaud Colas)
Migrate privacy switch, FileFields, history buttons, error messages, Datetimepicker, ordering icons, thumbnails, and user creation form controls to SVG icons (Thibaud Colas)
Switch form submission listings to use the same ordering icons as other listings (Thibaud Colas)
Include wagtail-factories in wagtail.test.utils to avoid cross-dependency issues (Matt Westcott)

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.

`wagtailsearch.Query` has moved to `wagtail.contrib.search_promotions`

The wagtailsearch.Query model has been moved from the search application to the contrib application wagtail.contrib.search_promotions. All imports will need to be updated and migrations will need to be run via a custom command, some imports will still work with a warning until a future version.

Migration command

If you have daily hits records in the wagtailsearch.Query you can run the management command to move these records to the new location.

./manage.py copy_daily_hits_from_wagtailsearch

Import updates

Import	Old import	New import
`Query` Model	`from wagtail.search.models import Query`	`from wagtail.contrib.search_promotions.models import Query`
`QueryForm`	`from wagtail.search.forms import QueryForm`	`from wagtail.contrib.search_promotions.forms import QueryForm`

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 auto-cleaning now relies on data attributes

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 Stimulus 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-value="true"
/>

Title field auto sync with the slug field on Pages now relies on data attributes

The title field will sync its value with the slug field on Pages if the Page is not published and the slug has not been manually changed. This JavaScript behaviour previously attached to any field with an ID of id_title, this has now changed to be any field with the appropriate Stimulus data attributes.

If your project is using the built in title and slug fields without any customisations, you will not need to do anything differently. However, if you were relying on this behaviour or the window.initSlugAutoPopulate global, please read ahead as you may need to make some changes to adopt the new approach.

There is a new Stimulus controller w-sync which allows any field to change one or more other fields when its value changes, the other field in this case will be the slug field (w-slug) with the id id_slug.

If you need to hook into this behaviour, the new approach will now correctly dispatch change events on the slug field. Alternatively, you can modify the data attributes on the fields to adjust this behaviour.

To adjust the target field (the one to be updated), you cam modify "data-w-sync-target-value", the default being "body:not(.page-is-live) [data-edit-form] #id_slug" (find the field with id id_slug when the page is not live).

To adjust what triggers the initial check (to see if the fields should be in sync), or the trigger to to the sync, you can use the Stimulus data-action attributes.

<input
    id="id_title"
    type="text"
    name="title"
    data-controller="w-sync"
    data-action="focus->w-sync#check blur->w-sync#apply change->w-sync#apply"
    data-w-sync-target-value="body:not(.page-is-live) #some_other_slug"
/>

Above we have adjusted these attributes to add a 'change' event listener to trigger the sync and also adjusted to look for a field with some_other_slug instead.

Progress button (`button-longrunning`) now relies on data attributes

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

JavaScript `window.addMessages` replaced with event dispatching

The undocumented window.addMessage function is no longer available and will throw an error if called, if similar functionality is required use DOM Event dispatching instead as follows.

// old
window.addMessage('success', 'Content has updated');

// new
document.dispatchEvent(
    new CustomEvent('w-messages:add', {
        detail: { text: 'Content has updated', type: 'success' },
    }),
);
// new (clearing existing messages before adding a new one)
document.dispatchEvent(
    new CustomEvent('w-messages:add', {
        detail: {
            clear: true,
            text: 'All content has updated',
            type: 'success',
        },
    }),
);
// message types 'success', 'error', 'warning' are supported

Note that this event name may change in the future and this functionality is still not officially supported.

Changes to StreamField `ValidationError` classes

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.

Additionally, the Python StreamBlockValidationError, ListBlockValidationError, StructBlockValidationError and TypedTableBlockValidationError classes no longer provide a params dict with block_errors and non_block_errors items; these are now available as the attributes block_errors and non_block_errors on the exception itself (or cell_errors and non_block_errors in the case of TypedTableBlockValidationError).

Snippets `delete-multiple` view removed

The ability to remove multiple snippet instances from the DeleteView and the undocumented wagtailsnippets_{app_label}_{model_name}:delete-multiple URL pattern have been removed. The view's functionality has been replaced by the delete action of the bulk actions feature introduced in Wagtail 4.0.

The delete bulk action view now also calls the {before,after}_delete_snippet hooks, in addition to the {before,after}_bulk_action hooks.

If you have customised the IndexView and/or DeleteView views in a SnippetViewSet subclass, make sure that the delete_multiple_url_name attribute is renamed to delete_url_name.

`status` classes are now `w-status`

Please update any custom styling or usage within the admin when working with status tags to the following new classes.

Old	New
`status-tag`	`w-status`
`primary`	`w-status--primary`
`disabled`	`w-status--disabled`
`status-tag--label`	`w-status--label`

Note that a new template tag has been built for usage within the admin that may make it easier to generate status tags.

{% load wagtailadmin_tags %}
{% status "live" url="/test-url/" title=trans_title hidden_label=trans_hidden_label classname="w-status--primary" attrs='target="_blank" rel="noreferrer"' %}
{% status status_label classname="w-status--primary" %}

5.0.md 23 KB 文件历史 原始文件