docs/releases/4.1.md
November 1, 2022
---
local:
depth: 1
---
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 to False in your settings. The new menu items can be removed and customized with the following hooks:
register_help_menu_item – to add new items to the "Help" menuconstruct_help_menu – to change or remove existing items from the "Help" menuconstruct_main_menu – to remove the new "Help" menu altogetherWhen 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 can 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 customized. See . This feature was developed by Sage Abdullah.
Snippet models that inherit from DraftStateMixin can now be assigned go-live and expiry dates. 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 .
This feature was developed by Karl Hobley and Matt Westcott.
There are multiple improvements to the documentation theme this release, here are some highlights.
PageQuerySet.private method as an alias of not_public (Mehrdad Moradizadeh)AbstractFormField to FormMixin and AbstractEmailForm to EmailFormMixin to allow use with subclasses of Page (Mehrdad Moradizadeh, Kurt Wall)docs.wagtail.org/.well-known/security.txt so that the security policy is available as per the specification on https://securitytxt.org/ (Jake Howard)classnames Wagtail admin template tag (Mehrdad Moradizadeh)admonition should not be used and titles for note are not supported, including clean up of some existing incorrect usage (LB (Ben Johnston)).button-secondary buttons across the admin interface (Paarth Agarwal)button not link for behaviour and remove support for disabled as a class (LB (Ben) Johnston)search type input in documentation search (LB (Ben) Johnston)help_text when set on FieldPanel, MultiFieldPanel, FieldRowPanel, and other panel APIs where it previously worked without official support (Matt Westcott)openpyxl, removing usage of XlsxWriter, tablib, xlrd and xlwt (Jaap Roes)button-secondary bicolor variants to the pattern library and styleguide (Adinapunyo Banerjee)id primary keys into Wagtail's generic views, including for custom Snippets and User models (Mehrdad Moradizadeh)<section> element so screen reader users can bypass them more easily (Thibaud Colas)update_index command can run without console output if called with --verbosity 0 (Ben Sturmfels, Oliver Parker)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)WagtailPageTestCase - assertPageIsRoutable, assertPageIsRenderable, assertPageIsEditable, assertPageIsPreviewable (Andy Babic)permission to PanelGroup, used by TabbedInterface, ObjectList, FieldRowPanel and MultiFieldPanel (Oliver Parker)PageQuerySet.not_public from returning all pages when no page restrictions exist (Mehrdad Moradizadeh)formfield_callback handling on ModelForm.Meta for future Django 4.2 release (Matt Westcott)ModelAdmin correctly supports filters in combination with subsequent searches without clearing the applied filters (Stefan Hammer)capitalize() calls to avoid issues with other languages or incorrectly presented model names for reporting and parts of site settings (Stefan Hammer)help_text for InlinePanel (Matt Westcott)for_user argument is passed to the form class when previewing pages (Matt Westcott)timesince_simple tag is consistently added in the template based on usage in context (Stefan Hammer)timesince_last_update and ensure the translated labels can be easier to work with in Transifex (Stefan Hammer)clean_name values in the Form Builder validation and increase performance of checks (Dan Bentley)wagtailsearch_editorspick table that prevents flushing the database (Matt Westcott)ChooserBlock.extract_references uses the model class, not the model string (Alex Tomkins)aria-labels (Matt Westcott)rebuild_references_index management commandAfter upgrading, you will need to run ./manage.py rebuild_references_index 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 .
WagtailPageTestCase in place of WagtailPageTestsWagtailPageTestCase is the base testing class and is now recommended over using WagtailPageTests .WagtailPageTests will continue to work and does log in the user on test setUp but may be deprecated in the future.# class MyPageTests(WagtailPageTests): # old
class MyPageTests(WagtailPageTestCase): # new
def setUp(self):
# WagtailPageTestCase will not log in during setUp - so add if needed
super().setUp()
self.login()
def test_can_create_a_page(self):
# ...
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 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.
The following button classes have been removed, none of which were being used within the admin but may have been used by custom code or packages:
button-neutralbutton-strokeonhoverhover-nounbuttonyes.xls Spreadsheet files into Redirects.xls legacy Microsoft Excel 97-2003 spreadsheets will no longer be supported for importing into the contrib Redirects listing..xlsx, .csv, .tsv formats are still supported.