docs/releases/4.2.md
February 6, 2023
---
local:
depth: 1
---
Wagtail now provides a set of utilities for creating data migrations on StreamField data. For more information, see StreamField data migrations. This feature was developed by Sandil Ranasinghe, initially as the wagtail-streamfield-migration-toolkit add-on package, as part of the Google Summer of Code 2022 initiative, with support from Jacob Topp-Mugglestone, Joshua Munn and Karl Hobley.
Snippets can now be locked by users to prevent other users from editing, through the use of the LockableMixin. For more details, see .
This feature was developed by Sage Abdullah.
Snippets can now be assigned to workflows through the use of the WorkflowMixin, allowing new changes to be submitted for moderation before they are published. For more details, see .
This feature was developed by Sage Abdullah.
fullpageurl template tagWagtail now provides a fullpageurl template tag (for both Django templates and Jinja2) to output a page's full URL including the domain. For more details, see .
This feature was developed by Jake Howard.
Wagtail now uses the Stimulus framework for client-side interactivity (see RFC 78). Our Outreachy contributor Loveth Omokaro has refactored significant portions of the admin interface:
Those changes improve the maintainability of the code, and help us move towards compatibility with strict CSP (Content Security Policy) rules. Thank you to Loveth and project mentors LB (Ben) Johnston, Thibaud Colas, and Paarth Agarwal.
The CMS now includes an accessibility checker in the user bar, to assist users in building more accessible websites and follow ATAG 2.0 guidelines. The checker, which is based on the Axe testing engine, is designed for content authors to identify and fix accessibility issues on their own. It scans the loaded page for errors and displays the results, with three rules turned on in this release. It’s configurable with the construct_wagtail_userbar hook.
This new feature was implemented by Albina Starykova as part of an Outreachy internship, with support from mentors Thibaud Colas, Sage Abdullah, and Joshua Munn.
Following feedback from Wagtail users on rich text UI improvements in Wagtail 4.0, we have further refined the behavior of rich text fields to cater for different scenarios:
Thank you to all who provided feedback, participants to our usability testing sessions, and to Nick Lee and Thibaud Colas for the implementation.
A new panel type is available. This is a variant of InlinePanel which improves the editor experience when adding large numbers of linked items - rather than creating and populating each sub-form individually, a chooser modal is opened allowing multiple objects to be selected at once.
This feature was developed by Matt Westcott, and sponsored by YouGov.
WagtailPageTestCase.assertCanCreate now supports the kwarg publish=True to determine whether to publish the page (Harry Percival, Akua Dokua Asiedu, Matt Westcott)rebuild_references_index command can run without console output if called with --verbosity 0 (Omerzahid Ali, Aman Pandey)button bicolor button--icon button-secondary including the button-small variant (Seremba Patrick)purge_embeds management command to delete all the cached embed objects in the database (Aman Pandey)form_fields as an APIField on FormPage (Sævar Öfjörð Magnússon, Suyash Singh, LB (Ben) Johnston)DraftStateMixin now automatically define a "Publish" permission type (Sage Abdullah)azure-mgmt-cdn version >= 10 and azure-mgmt-frontdoor version >= 1 in the frontend cache invalidator (Sylvain Fankhauser)django-storages backend is configured to allow overwriting (Rishabh Jain)ChooserBlock.extract_references uses the model class, not the model string (Alex Tomkins)InlinePanel inner fields to avoid lost or incorrectly linked comments (Jacob Topp-Mugglestone)WAGTAILIMAGES_FEATURE_DETECTION_ENABLED to avoid errors for images that do not exist (Aman Pandey)cc, bcc and reply_to to the Django mail helper from wagtail.admin.mail.send_mail (Ben Gosney)DecimalBlock correctly handles None, when required=False, values (Natarajan Balaji)delete_url_name attribute in generic DeleteView (Alex Simpson)wagtail.search.utils.parse_query_string (Beniamin Bucur)latest_revision pointer from being copied over when copying translatable snippets for translation (Sage Abdullah)fnm over nvm in development documentation (LB (Ben) Johnston)request and current_site to get_url on the performance documentation page (Jake Howard)register_user_listing_buttons hook (LB (Ben Johnston))page models usage guide (Damilola Oladele)register_image_operations and add an example of a custom Image filter (Coen van der Kamp)RichTextField (Matt Westcott)renderer_classes (Aman Pandey)testapp migrations (Matt Westcott)escapeHtml function (Jordan Rob)initButtonSelects from core.js to own TypeScript file and add unit tests (Loveth Omokaro)initSkipLink util to TypeScript and add JSDoc & unit tests (Juliet Adeboye)unlist to Tailwind utility class w-list-none (Loveth Omokaro)hasOwn in TypeScript (Loveth Omokaro)initTooltips to TypeScript and add JSDoc and unit tests (Fatuma Abdullahi)initTagField from core.js to own TypeScript file and add unit tests (Chisom Okeoma)initDismissibles (Yekasumah)classname for passing HTML class attributes (LB (Ben Johnston))InlinePanel JavaScript initialization code and adopt a class approach (Matt Westcott)identity JavaScript util into shared utils folder (LB (Ben Johnston))URLSearchParams (Loveth Omokaro)tsconfig to better support modern TypeScript development and clean up some code quality issues via Eslint (Loveth Omokaro)wagtail.admin.panels into submodules, existing exports have been preserved (Matt Westcott)wagtail.core and other imports deprecated in Wagtail 3.0 (Matt Westcott)avatar component with a template tag include {% avatar ... %} throughout the admin interface (Aman Pandey)WagtailImageField)The AbstractImage and AbstractRendition models use a Wagtail-specific WagtailImageField which extends Django's ImageField
to use Willow for image file handling. This will generate a new migration if you
are using a custom image model.
InlinePanel not supportedWhen the commenting system was introduced, support for InlinePanel fields was incorrectly added. This has led to issues
where comments can be lost on save, or in most cases will be added to the incorrect item within the InlinePanel. The ability
to add comments here has now been removed and as such any existing comments that were added will no longer show.
See https://github.com/wagtail/wagtail/issues/9685 for tracking of adding this back officially in the future.
classname convention for some template tags & includesSome undocumented Wagtail admin template tags and includes have been refactored to adopt a more consistent naming of classname.
If these are used within packages or customizations they will need to be updated to the new variable naming convention.
| Name | New (classname) | Old (various) |
|---|---|---|
icon (see note) | {% icon name='spinner' classname='...' %} | {% icon name='spinner class_name='...' %} |
dialog_toggle | {% dialog_toggle classname='...' %} | {% dialog_toggle class_name='...' %} |
paginate | {% paginate pages classname="..." %} | {% paginate pages classnames="..." %} |
tab_nav_link | {% include 'wagtailadmin/shared/tabs/tab_nav_link.html' with classname="..." %} | {% include 'wagtailadmin/shared/tabs/tab_nav_link.html' with classes="..." %} |
side_panel_button | {% include 'wagtailadmin/shared/side_panels/includes/side_panel_button.html' with classname="..." %} | {% include 'wagtailadmin/shared/side_panels/includes/side_panel_button.html' with classes="..." %} |
Note that the icon template tag will still support class_name with a deprecation warning. Support will be dropped in a future release.
InlinePanel JavaScript function is now a classThe (internal, undocumented) InlinePanel JavaScript function, used to initialize client-side behavior for inline panels, has been converted to a class. Any user code that calls this function should now replace InlinePanel(...) calls with new InlinePanel(...). Additionally, child form controls are now initialized automatically, and so it is no longer necessary to call initChildControls, updateChildCount, updateMoveButtonDisabledStates or updateAddButtonState.
Python code that uses the InlinePanel panel type is not affected by this change.
WAGTAILADMIN_GLOBAL_PAGE_EDIT_LOCK setting is now WAGTAILADMIN_GLOBAL_EDIT_LOCKThe WAGTAILADMIN_GLOBAL_PAGE_EDIT_LOCK setting has been renamed to WAGTAILADMIN_GLOBAL_EDIT_LOCK.
The wagtailuserbar template tag now initializes the userbar as a Web Component, with a wagtail-userbar custom element using shadow DOM to apply styles without any collisions with the host page.
For any site customizing the position of the userbar, target the styles to wagtail-userbar::part(userbar) instead of .wagtail-userbar. For example:
wagtail-userbar::part(userbar) {
bottom: 30px;
}
Like other userbar items, the new accessibility checker is configurable with the construct_wagtail_userbar hook. For example, to remove the new item, use:
from wagtail.admin.userbar import AccessibilityItem
@hooks.register('construct_wagtail_userbar')
def remove_userbar_accessibility_checks(request, items):
items[:] = [item for item in items if not isinstance(item, AccessibilityItem)]
azure-mgmt-cdn and azure-mgmt-frontdoor packages will be droppedIf you are using the front-end cache invalidator module (wagtail.contrib.frontend_cache) with Azure CDN or Azure Front Door, the following packages need to be updated:
azure-mgmt-cdn to version 10 or aboveazure-mgmt-frontdoor to version 1 or aboveSupport for older versions will be dropped in a future release.
Workflow and Task methodsTo accommodate workflows support for snippets, the page parameter in {meth}Workflow.start() <wagtail.models.Workflow.start> has been renamed to obj.
In addition, some methods on the base {class}~wagtail.models.Task model have been changed. If you have {doc}custom Task types </extending/custom_tasks>, make sure to update the methods to reflect the following changes:
page_locked_for_user() is now {meth}~wagtail.models.Task.locked_for_user. Using page_locked_for_user() is deprecated and will be removed in a future release.page parameter in user_can_access_editor(), locked_for_user(), user_can_lock(), user_can_unlock(), get_actions(), has been renamed to obj.WorkflowState and TaskState modelsTo accommodate workflows support for snippets, the WorkflowState.page foreign key has been replaced with a GenericForeignKey as WorkflowState.content_object. The generic foreign key is defined using a combination of the new WorkflowState.base_content_type and WorkflowState.object_id fields.
The TaskState.page_revision foreign key has been renamed to TaskState.revision.
wagtail.admin.forms.search.SearchForm validation logicThe wagtail.admin.forms.search.SearchForm class (which is internal and undocumented, but may be in use by applications that extend the Wagtail admin) no longer treats an empty search field as invalid. Any code that checks form.is_valid to determine whether or not to apply a search() filter to a queryset should now explicitly check that form.cleaned_data["q"] is non-empty.