Wagtail 4.1 is designated a Long Term Support (LTS) release. Long Term Support releases will continue to receive maintenance updates as necessary to address security and data-loss related issues, up until the next LTS release (typically a period of 12 months).
To help with onboarding new users, Wagtail now displays a banner on the dashboard, pointing users to our Editor Guide. The sidebar also contains a new "Help" menu item with a prominent indicator to call attention to the new content: a "What’s new" page showcasing new features, and a link to the Editor Guide.
Users can dismiss the new banner and the sidebar items’ indicators by interacting with the corresponding UI element. We store the state in the user’s profile so we only call attention to the content once.
To turn off the new banner, set [`WAGTAIL_ENABLE_WHATS_NEW_BANNER`](wagtail_enable_whats_new_banner) to `False` in your settings. The new menu items can be removed and customised with the following hooks:
- [`register_help_menu_item`](register_help_menu_item) – to add new items to the "Help" menu
- [`construct_help_menu`](construct_help_menu) –to change or remove existing items from the "Help" menu
- [`construct_main_menu`](construct_main_menu) –to remove the new "Help" menu altogether
When navigating long page editing interfaces, it can be tedious to pinpoint a specific section, or find all validation errors. To help with those tasks, the page editor now has a new "minimap" side panel, with a table of contents of all sections on the form. Clicking a section’s label scrolls straight to this part of the page, and an indicator bar represents which sections are currently visible on the page. When validation errors are present, each section shows a count of the number of errors. This feature was implemented by Thibaud Colas based on a prototype by LB (Ben) Johnston.
Scheduled publishing settings can now be found within the Status side panel of the page editing view. This change aims to improve clarity over who is able to set schedules, and when they take effect. This feature was developed by Sage Abdullah.
The `register_snippet` function now accepts a `SnippetViewSet` class, allowing various aspects of the snippet's admin views to be customised. See [](wagtailsnippets_custom_admin_views). This feature was developed by Sage Abdullah.
Images, documents and snippets now provide a usage report, listing the places where references to those objects appear. This report is powered by a new `ReferenceIndex` model which records cross-references between objects whenever those objects to save; this allows it to work more efficiently than the old report available through the `WAGTAIL_USAGE_COUNT_ENABLED` setting, as well as handling references within StreamField and rich text fields.
Note that on first upgrading to Wagtail 4.1, you will need to run the `rebuild_references_index` management command to populate the references table and ensure that reference counts are displayed accurately. By default, references are tracked for all models in the project, including ones not managed through Wagtail - to disable this for specific models, see [](managing_the_reference_index).
There are multiple improvements to the documentation theme this release, here are some highlights.
* Code snippets now have a quick copy to clipboard button (Mohammad Areeb)
* Improve the dark mode theme adoption, avoid flashing the wrong theme on first load, reduce the need for scrollbars in page TOC, link underline fixes in Safari (LB (Ben) Johnston, Kartik Kankurte)
* Better accessibility support with a skip to content link (LB (Ben) Johnston)
* Optimise the performance of the Wagtail userbar to remove duplicated queries, improving page loads when viewing live pages while signed in (Jake Howard)
* Pull out behaviour from `AbstractFormField` to `FormMixin` and `AbstractEmailForm` to `EmailFormMixin` to allow use with subclasses of `Page` [](form_builder_mixins) (Mehrdad Moradizadeh, Kurt Wall)
* Add a `docs.wagtail.org/.well-known/security.txt` so that the security policy is available as per the specification on [https://securitytxt.org/](https://securitytxt.org/) (Jake Howard)
* Show an inverse locked indicator when the page has been locked by the current user in reports and dashboard listings (Vaibhav Shukla, LB (Ben Johnston))
* Add clarity to the development documentation that `admonition` should not be used and titles for `note` are not supported, including clean up of some existing incorrect usage (LB (Ben Johnston))
* Render `help_text` when set on `FieldPanel`, `MultiFieldPanel`, `FieldRowPanel`, and other panel APIs where it previously worked without official support (Matt Westcott)
* Adopt generic class based views for the create User create view, User edit view, user delete view and Users index listing / search results (Mehrdad Moradizadeh)
* Add better support for non-integer / non-`id` primary keys into Wagtail's generic views, including for custom Snippets and User models (Mehrdad Moradizadeh)
* The `image_url` template tag, when using the serve view to redirect rather than serve directly, will now use temporary redirects with a cache header instead of permanent redirects (Jake Howard)
* Add new test assertions to `WagtailPageTestCase` - `assertPageIsRoutable`, `assertPageIsRenderable`, `assertPageIsEditable`, `assertPageIsPreviewable` (Andy Babic)
* Add ability to provide a required `permission` to `PanelGroup`, used by `TabbedInterface`, `ObjectList`, `FieldRowPanel` and `MultiFieldPanel` (Oliver Parker)
* Remove `capitalize()` calls to avoid issues with other languages or incorrectly presented model names for reporting and parts of site settings (Stefan Hammer)
* Ensure the capitalisation of the `timesince_simple` tag is consistently added in the template based on usage in context (Stefan Hammer)
* Add missing translation usage for the `timesince_last_update` and ensure the translated labels can be easier to work with in Transifex (Stefan Hammer)
After upgrading, you will need to run `./manage.py rebuild_references_index` in order to populate the references table and ensure that usage counts for images, documents and snippets are displayed accurately. By default, references are tracked for all models in the project, including ones not managed through Wagtail - to disable this for specific models, see [](managing_the_reference_index).
The `button-secondary` class is no longer compatible with either the `.serious` or `.no` classes, this partially worked previously but is no longer officially supported.
When adding custom buttons using the `ModelAdmin``ButtonHelper` class, custom buttons will no longer include the `button-secondary` class by default in index listings.
If using the hook `register_user_listing_buttons` to register buttons along with the undocumented `UserListingButton` class, the `button-secondary` class will no longer be included by default.
Avoid using `disabled` as a class on `button` elements, instead use the [`disabled` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/disabled) as support for this as a class may be removed in a future version of Wagtail and is not accessible.
If using custom `expanding-formset` the add button will no longer support the `disabled` class but instead must require the `disabled` attribute to be set.
