wagtail/docs/releases/4.0.md

Wagtail 4.0 release notes - IN DEVELOPMENT

---
local:
depth: 1
---

What's new

Image renditions can now be prefetched by filter

When using a queryset to render a list of images, you can now use the prefetch_renditions() queryset method to prefetch the renditions needed for rendering with a single extra query, similar to prefetch_related. If you have many renditions per image, you can also call it with filters as arguments - prefetch_renditions("fill-700x586", "min-600x400") - to fetch only the renditions you intend on using for a smaller query. For long lists of images, this can provide a significant boost to performance. See [](prefetching_image_renditions) for more examples. This feature was developed by Tidiane Dia and Karl Hobley.

Other features

• Add clarity to confirmation when being asked to convert an external link to an internal one (Thijs Kramer)
• Convert various pages in the documentation to Markdown (Khanh Hoang, Vu Pham, Daniel Kirkham, LB (Ben) Johnston, Thiago Costa de Souza, Benedict Faw, Noble Mittal, Sævar Öfjörð Magnússon, Sandeep M A, Stefano Silvestri)
• Add base_url_path to ModelAdmin so that the default URL structure of app_label/model_name can be overridden (Vu Pham, Khanh Hoang)
• Add full_url to the API output of ImageRenditionField (Paarth Agarwal)
• Use InlinePanel's label when available for field comparison label (Sandil Ranasinghe)
• Drop support for Safari 13 by removing left/right positioning in favour of CSS logical properties (Thibaud Colas)
• Use FormData instead of jQuery's form.serialize when editing documents or images just added so that additional fields can be better supported (Stefan Hammer)
• Add informational Codecov status checks for GitHub CI pipelines (Tom Hu)
• Make it possible to reuse and customise Wagtail’s fonts with CSS variables (LB (Ben) Johnston)
• Add better handling and informative developer errors for cross linking URLS (e.g. success after add) in generic views wagtail.admin.views.generic (Matt Westcott)
• Introduce wagtail.admin.widgets.chooser.BaseChooser to make it easier to build custom chooser inputs (Matt Westcott)
• Introduce JavaScript chooser module, including a SearchController class which encapsulates the standard pattern of re-rendering the results panel in response to search queries and pagination (Matt Westcott)
• Add ability to select multiple items at once within bulk actions selections when holding shift on subsequent clicks (Hitansh Shah)
• Upgrade notification, shown to admins on the dashboard if Wagtail is out of date, will now link to the release notes for the closest minor branch instead of the latest patch (Tibor Leupold)
• Upgrade notification can now be configured to only show updates when there is a new LTS available via WAGTAIL_ENABLE_UPDATE_CHECK = 'lts' (Tibor Leupold)
• Implement redesign of the Workflow Status dialog, fixing accessibility issues (Steven Steinwand)
• Add the ability to change the number of images displayed per page in the image library (Tidiane Dia, with sponsorship from YouGov)
• Allow users to sort by different fields in the image library (Tidiane Dia, with sponsorship from YouGov)
• Add prefetch_renditions method to ImageQueryset for performance optimisation on image listings (Tidiane Dia, Karl Hobley)
• Add ability to define a custom get_field_clean_name method when defining FormField models that extend AbstractFormField (LB (Ben) Johnston)
• Migrate Home (Dashboard) view to use generic Wagtail class based view (LB (Ben) Johnston)
• Combine most of Wagtail’s stylesheets into the global core.css file (Thibaud Colas)
• Add new Breadcrumbs and Tabs to the Wagtail pattern library (Paarth Agarwal)
• Adopt new Page Editor UI tabs in the workflow history report page (Paarth Agarwal)
• Update ReportView to extend from generic wagtail.admin.views.generic.models.IndexView (Sage Abdullah)
• Introduce a wagtail.admin.viewsets.chooser.ChooserViewSet module to serve as a common base implementation for chooser modals (Matt Westcott)
• Add documentation for wagtail.admin.viewsets.model.ModelViewSet (Matt Westcott)
• Enhance new breadcrumbs so they can be added to any header or container element (Paarth Agarwal)
• Adopt new breadcrumbs on the page explorer (listing) view and the page chooser modal, remove legacy breadcrumbs code for move page as no longer used (Paarth Agarwal)
• Added multi-site support to the API (Sævar Öfjörð Magnússon)
• Add add_to_admin_menu option for ModelAdmin (Oliver Parker)
• Implement Fuzzy matching for Elasticsearch (Nick Smith)
• Cache model permission codenames in PermissionHelper (Tidiane Dia)
• Selecting a new parent page for moving a page now uses the chooser modal which allows searching (Viggo de Vries)
• Add clarity to the search indexing documentation for how boost works when using Postgres with the database search backend (Tibor Leupold)
• Rename explorer_breadcrumb template tag to breadcrumbs as it is now used in multiple locations (Paarth Agarwal)
• Updated django-filter version to support 23 (Yuekui)
• Use .iterator() in a few more places in the admin, to make it more stable on sites with many pages (Andy Babic)
• Migrate some simple React component files to TypeScript (LB (Ben) Johnston)
• Deprecate the usage and documentation of the wagtail.contrib.modeladmin.menus.SubMenu class, provide a warning if used directing developers to use wagtail.admin.menu.Menu instead (Matt Westcott)
• Remove legacy (non-next) breadcrumbs no longer used, remove ModelAdmin usage of breadcrumbs completely (Paarth Agarwal)
• Replace human-readable-date hover pattern with accessible tooltip variant across all of admin (Bernd de Ridder)
• Added WAGTAILADMIN_USER_PASSWORD_RESET_FORM setting for overriding the admin password reset form (Michael Karamuth)
• Prefetch workflow states in edit page view to to avoid queries in other parts of the view/templates that need it (Tidiane Dia)
• Remove the edit link from edit bird in previews to avoid confusion (Sævar Öfjörð Magnússon)
• Introduce new template fragment and block level enclosure tags for easier template composition (Thibaud Colas)

Bug fixes

• Fix issue where ModelAdmin index listings with export list enabled would show buttons with an incorrect layout (Josh Woodcock)
• Fix typo in ResumeWorkflowActionFormatter message (Stefan Hammer)
• Throw a meaningful error when saving an image to an unrecognised image format (Christian Franke)
• Remove extra padding for headers with breadcrumbs on mobile viewport (Steven Steinwand)
• Replace PageRevision with generic Revision model (Sage Abdullah)
• Ensure that custom document or image models support custom tag models (Matt Westcott)
• Ensure comments use translated values for their placeholder text (Stefan Hammer)
• Ensure the upgrade notification, shown to admins on the dashboard if Wagtail is out of date, content is translatable (LB (Ben) Johnston)
• Only show the re-ordering option to users that have permission to publish pages within the page listing (Stefan Hammer)
• Ensure default sidebar branding (bird logo) is not cropped in RTL mode (Steven Steinwand)
• Add an accessible label to the image focal point input when editing images (Lucie Le Frapper)
• Remove unused header search JavaScript on the redirects import page (LB (Ben) Johnston)
• Ensure non-square avatar images will correctly show throughout the admin (LB (Ben) Johnston)
• Ignore translations in test files and re-include some translations that were accidentally ignored (Stefan Hammer)
• Show alternative message when no page types are available to be created (Jaspreet Singh)
• Prevent error on sending notifications for the legacy moderation process when no user was specified (Yves Serrano)
• Ensure aria-label is not set on locale selection dropdown within page chooser modal as it was a duplicate of the button contents (LB (Ben Johnston))
• Revise the ModelAdmin title column behaviour to only link to 'edit' if the user has the correct permissions, fallback to the 'inspect' view or a non-clickable title if needed (Stefan Hammer)
• Ensure that DecimalBlock preserves the Decimal type when retrieving from the database (Yves Serrano)
• When no snippets are added, ensure the snippet chooser modal would have the correct URL for creating a new snippet (Matt Westcott)
• ngettext in Wagtail's internal JavaScript internationalisation utilities now works (LB (Ben) Johnston)
• Ensure the linting/formatting npm scripts work on Windows (Anuja Verma)

Upgrade considerations

base_url_path keyword argument added to AdminURLHelper

The wagtail.contrib.modeladmin.helpers.AdminURLHelper class now accepts a base_url_path keyword argument on its constructor. Custom subclasses of this class should be updated to accept this keyword argument.

Dropped support for Safari 13

Safari 13 will no longer be officially supported as of this release, this deviates the current support for the last 3 version of Safari by a few months and was required to add better support for RTL languages.

PageRevision replaced with Revision

The PageRevision model has been replaced with a generic Revision model. If you use the PageRevision model in your code, make sure that:

• Creation of PageRevision objects should be updated to create Revision objects using the page's id as the object_id, the default Page model's content type as the base_content_type, and the page's specific content type as the content_type.
• Queries that use the PageRevision.objects manager should be updated to use the Revision.page_revisions manager.
• Revision queries that use Page.id should be updated to cast the Page.id to a string before using it in the query (e.g. by using str() or Cast("page_id", output_field=CharField())).
• Page queries that use PageRevision.page_id should be updated to cast the Revision.object_id to an integer before using it in the query (e.g. by using int() or Cast("object_id", output_field=IntegerField())).
• Access to PageRevision.page should be updated to Revision.content_object.

If you maintain a package across multiple Wagtail versions that includes a model with a ForeignKey to the PageRevision model, you can create a helper function to correctly resolve the model depending on the installed Wagtail version, for example:

from django.db import models
from wagtail import VERSION as WAGTAIL_VERSION


def get_revision_model():
    if WAGTAIL_VERSION >= (4, 0):
        return "wagtailcore.Revision"
    return "wagtailcore.PageRevision"


class MyModel(models.Model):
    # Before
    # revision = models.ForeignKey("wagtailcore.PageRevision")
    revision = models.ForeignKey(get_revision_model(), on_delete=models.CASCADE)

Page.get_latest_revision_as_page renamed to Page.get_latest_revision_as_object

The Page.get_latest_revision_as_page method has been renamed to Page.get_latest_revision_as_object. The old name still exists for backwards-compatibility, but calling it will raise a RemovedInWagtail50Warning.

AdminChooser replaced with BaseChooser

Custom choosers should no longer use wagtail.admin.widgets.chooser.AdminChooser which has been replaced with wagtail.admin.widgets.chooser.BaseChooser.

get_snippet_edit_handler moved to wagtail.admin.panels.get_edit_handler

The get_snippet_edit_handler function in wagtail.snippets.views.snippets has been moved to get_edit_handler in wagtail.admin.panels.

explorer_breadcrumb template tag has been renamed to breadcrumbs, move_breadcrumb has been removed

The explorer_breadcrumb template tag is not documented, however if used it will need to be renamed to breadcrumbs and the url_name is now a required arg.

The move_breadcrumb template tag is no longer used and has been removed.

wagtail.contrib.modeladmin.menus.SubMenu is deprecated

The wagtail.contrib.modeladmin.menus.SubMenu class should no longer be used for constructing submenus of the admin sidebar menu. Instead, import wagtail.admin.menu.Menu and pass the list of menu items as the items keyword argument.

createSnippetChooser replaced with SnippetChooser class

The JavaScript function createSnippetChooser(id) has been deprecated; user code should call new SnippetChooser(id) instead.

URL route names for document and snippet apps have changed

If your code contains references to URL route names within the wagtaildocs or wagtailsnippets namespaces, these should be updated as follows:

• wagtaildocs:chooser is now wagtaildocs_chooser:choose
• wagtaildocs:chooser_results is now wagtaildocs_chooser:choose_results
• wagtaildocs:document_chosen is now wagtaildocs_chooser:chosen
• wagtaildocs:chooser_upload is now wagtaildocs_chooser:create
• wagtailsnippets:list, wagtailsnippets:list_results, wagtailsnippets:add, wagtailsnippets:edit, wagtailsnippets:delete-multiple, wagtailsnippets:delete, wagtailsnippets:usage, wagtailsnippets:history: These now exist in a separate wagtailsnippets_{app_label}_{model_name} namespace for each snippet model, and no longer take app_label and model_name as arguments.
• wagtailsnippets:choose, wagtailsnippets:choose_results, wagtailsnippets:chosen: These now exist in a separate wagtailsnippetchoosers_{app_label}_{model_name} namespace for each snippet model, and no longer take app_label and model_name as arguments.