wagtail/docs/releases/4.0.md

291 wiersze
25 KiB
Markdown
Czysty Wina Historia

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

# Wagtail 4.0 release notes - IN DEVELOPMENT
```{contents}
---
local:
depth: 1
---
```
## What's new
### Global settings models
The new `BaseGenericSetting` base model class allows defining a settings model that applies to all sites rather than just a single site.
See [the Settings documentation](/reference/contrib/settings) for more information. This feature was implemented by Kyle Bayliss.
### 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.
### Rich text improvements
As part of the page editor redesign project sponsored by Google, we have made a number of improvements to our rich text editor:
* Inline toolbar: The toolbar now shows inline, to avoid clashing with the pages header.
* Command palette: Start a block with a slash / to open the palette and change the text format.
* Character count: The character count is displayed underneath the editor, live-updating as you type. This counts the length of the text, not of any formatting.
* Paste to auto-create links: To add a link from your copy-paste clipboard, select text and paste the URL.
* Text shortcuts undo: The editor normally converts text starting with `1. ` to a list item. Its now possible to un-do this change and keep the text as-is. This works for all Markdown-style shortcuts.
* RTL support: The editors UI now displays correctly in right-to-left languages.
* Focus-aware placeholder: The editors placeholder text will now follow the users focus, to make it easier to understand where to type in long fields.
* Empty heading highlight: The editor now highlights empty headings and list items by showing their type (“Heading 3”) as a placeholder, so content is less likely to be published with empty headings.
### Live preview panel
Wagtails page preview is now available in a side panel within the page editor. This preview auto-updates as users type, and can display the page in three different viewports: mobile, tablet, desktop. The existing preview functionality is still present, moved inside the preview panel rather than at the bottom of the page editor. The auto-update delay can be configured with the `WAGTAIL_AUTO_UPDATE_PREVIEW_INTERVAL` setting. This feature was developed by Sage Abdullah.
### Admin colour themes
In Wagtail 2.12, we introduced theming support for Wagtails primary brand colour. This has now been extended to almost all of Wagtails colour palette. View our [](custom_user_interface_colours) documentation for more information, an overview of Wagtails customisable colour palette, and a live demo of the supported customisations. This was implemented by Thibaud Colas, under the page editor redesign project sponsored by Google.
### Windows High Contrast mode support improvements
In Wagtail 2.16, we introduced support for Windows High Contrast mode (WHCM). This release sees a lot of improvements to our support, thanks to our new contributor Anuja Verma, who has been working on this as part of the [Contrast Themes](https://github.com/wagtail/wagtail/discussions/8193) Google Summer of Code project, with support from Jane Hughes, Scott Cranfill, and Thibaud Colas.
* Improve help block styles with less reliance on communication via colour alone in forced colors mode
* Add a bottom border to top messages so they stand out from the header in forced colors mode
* Make progress bars progress visible in forced colors mode
* Make checkboxes visible in forced colors mode
* Display the correct color for icons in forced colors mode
* Add a border around modal dialogs so they can be identified in forced colors mode
### 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 Wagtails 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)
* Migrate Image and Document choosers to ne JavaScript chooser module (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 Wagtails 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](api_filtering_pages_by_site) to the API (Sævar Öfjörð Magnússon)
* Add `add_to_admin_menu` option for ModelAdmin (Oliver Parker)
* Implement [Fuzzy matching](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)
* Add a `classnames` template tag to easily build up classes from variables provided to a template (Paarth Agarwal)
* Migrate the dashboard (home) view header to the shared header template and update designs (Paarth Agarwal)
* Update classes and styles for the shared header templates to align with UI guidelines (Paarth Agarwal)
* Clean up multiple eslint rules usage and configs to align better with the Wagtail coding guidelines (LB (Ben Johnston))
* Make ModelAdmin InspectView footer actions consistent with other parts of the UI (Thibaud Colas)
* Switch all report workflow, redirects, form submissions, site settings views to use Wagtails reusable header component (Paarth Agarwal)
* Add support for Twitter and other text-only embeds in Draftail embed previews (Iman Syed, Paarth Agarwal)
* Use new modal dialog component for privacy settings modal (Sage Abdullah)
* Add `menu_item_name` to modify MenuItem's name for ModelAdmin (Alexander Rogovskyy, Vu Pham)
* Add an extra confirmation prompt when deleting pages with a large number of child pages (Jaspreet Singh)
* Adopt the slim header in page listing views, with buttons moved under the "Actions" dropdown, including addition of translation page in the parent "more" button (Paarth Agarwal)
* Replace latin abbreviations (i.e. / e.g.) with common English phrases so that documentation is easier to understand (Dominik Lech)
* Add shortcut for accessing StreamField blocks by block name with new [`blocks_by_name` and `first_block_by_name` methods on `StreamValue`](streamfield_retrieving_blocks_by_name) (Tidiane Dia, Matt Westcott)
* Add HTML-aware max_length validation on RichTextField and RichTextBlock (Matt Westcott)
* Remove `is_parent` kwarg in various page button hooks as this approach is no longer required (Paarth Agarwal)
* Improve security of redirect imports by adding a file hash (signature) check for so that any tampering of file contents between requests will throw a `BadSignature` error (Jaap Roes)
* Refresh designs for Home (Dashboard) site summary panels, use theme spacing and colours, add support for RTL layouts and better support for small devices (Paarth Agarwal, LB (Ben) Johnston)
### 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)
* Fix display of dates in exported xlsx files on macOS Preview and Numbers (Jaap Roes)
* Remove outdated reference to 30-character limit on usernames in help text (minusf)
* Resolve multiple form submissions index listing page layout issues including title not being visible on mobile and interaction with large tables (Paarth Agarwal)
* Ensure ModelAdmin single selection lists show correctly with Django 4.0 form template changes (Coen van der Kamp)
* Ensure icons within help blocks have accessible contrasting colours, and links have a darker colour plus underline to indicate they are links (Paarth Agarwal)
* Ensure consistent sidebar icon position whether expanded or collapsed (Scott Cranfill)
* Avoid redirects import error if the file had lots of columns (Jaap Roes)
* Resolve accessibility and styling issues with the expanding status panel (Sage Abdullah)
* Avoid 503 `AttributeError` when an empty search param `q=` is combined with other filters in the Images index view (Paritosh Kabra)
## Upgrade considerations
### Changes to `Page.serve()` and `Page.serve_preview()` methods
As part of making previews available to non-page models, the `serve_preview()` method has been decoupled from the `serve()` method and extracted into the `PreviewableMixin` class. If you have overridden the `serve()` method in your page models, you will likely need to override `serve_preview()`, `get_preview_template()`, and/or `get_preview_context()` methods to handle previews accordingly. Alternatively, you can also override the `preview_modes` property to return an empty list to disable previews.
### `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:
```python
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.
### Chooser widget JavaScript initialisers replaced with classes
The internal JavaScript functions `createPageChooser`, `createSnippetChooser`, `createDocumentChooser` and `createImageChooser` used for initialising chooser widgets have been replaced by classes, and user code that calls them needs to be updated accordingly:
* `createPageChooser(id)` should be replaced with `new PageChooser(id)`
* `createSnippetChooser(id)` should be replaced with `new SnippetChooser(id)`
* `createDocumentChooser(id)` should be replaced with `new DocumentChooser(id)`
* `createImageChooser(id)` should be replaced with `newImageChooser(id)`
### URL route names for image, document and snippet apps have changed
If your code contains references to URL route names within the `wagtailimages`, `wagtaildocs` or `wagtailsnippets` namespaces, these should be updated as follows:
* `wagtailimages:chooser` is now `wagtailimages_chooser:choose`
* `wagtailimages:chooser_results` is now `wagtailimages_chooser:choose_results`
* `wagtailimages:image_chosen` is now `wagtailimages_chooser:chosen`
* `wagtailimages:chooser_upload` is now `wagtailimages_chooser:create`
* `wagtailimages:chooser_select_format` is now `wagtailimages_chooser:select_format`
* `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.
### Auto-updating preview
As part of the introduction of the new live preview panel, we have changed the `WAGTAIL_AUTO_UPDATE_PREVIEW` setting to be on (`True`) by default. This can still be turned off by setting it to `False`. The `WAGTAIL_AUTO_UPDATE_PREVIEW_INTERVAL` setting has been introduced for sites willing to reduce the performance cost of the live preview without turning it off completely.
### Slim header on page listings
The page explorer listings now use Wagtails new slim header, replacing the previous large teal header. The parent pages metadata and related actions are now available within the “Info” side panel, while the majority of buttons are now available under the Actions dropdown in the header, identically to the page create/edit forms.
Customising which actions are available and adding extra actions is still possible, but has to be done with the [`register_page_header_buttons`](register_page_header_buttons) hook, rather than [`register_page_listing_buttons`](register_page_listing_buttons) and [`register_page_listing_more_buttons`](register_page_listing_more_buttons). Those hooks still work as-is to define actions for each page within the listings.
### `is_parent` removed from page button hooks
* The following hooks `construct_page_listing_buttons`, `register_page_listing_buttons`, `register_page_listing_more_buttons` no longer accept the `is_parent` keyword argument and this should be removed.
* `is_parent` was the previous approach for determining whether the buttons would show in the listing rows or the page's more button, this can be now achieved with discrete hooks instead.
### Changed CSS variables for admin colour themes
As part of our support for theming across all colors, weve had to rename or remove some of the pre-existing CSS variables. Wagtails indigo is now customisable with `--w-color-primary`, and the teal is customisable as `--w-color-secondary`. See [](custom_user_interface_colours) for an overview of all customisable colours. Here are replaced variables:
- `--color-primary` is now `--w-color-secondary`
- `--color-primary-hue` is now `--w-color-secondary-hue`
- `--color-primary-saturation` is now `--w-color-secondary-saturation`
- `--color-primary-lightness` is now `--w-color-secondary-lightness`
- `--color-primary-darker` is now `--w-color-secondary-400`
- `--color-primary-darker-hue` is now `--w-color-secondary-400-hue`
- `--color-primary-darker-saturation` is now `--w-color-secondary-400-saturation`
- `--color-primary-darker-lightness` is now `--w-color-secondary-400-lightness`
- `--color-primary-dark` is now `--w-color-secondary-600`
- `--color-primary-dark-hue` is now `--w-color-secondary-600-hue`
- `--color-primary-dark-saturation` is now `--w-color-secondary-600-saturation`
- `--color-primary-dark-lightness` is now `--w-color-secondary-600-lightness`
- `--color-primary-lighter` is now `--w-color-secondary-100`
- `--color-primary-lighter-hue` is now `--w-color-secondary-100-hue`
- `--color-primary-lighter-saturation` is now `--w-color-secondary-100-saturation`
- `--color-primary-lighter-lightness` is now `--w-color-secondary-100-lightness`
- `--color-primary-light` is now `--w-color-secondary-50`
- `--color-primary-light-hue` is now `--w-color-secondary-50-hue`
- `--color-primary-light-saturation` is now `--w-color-secondary-50-saturation`
- `--color-primary-light-lightness` is now `--w-color-secondary-50-lightness`
Weve additionally removed all `--color-input-focus` and `--color-input-focus-border` variables, as Wagtails form fields no longer have a different color on focus.
### `WAGTAILDOCS_DOCUMENT_FORM_BASE` and `WAGTAILIMAGES_IMAGE_FORM_BASE` must inherit from `BaseDocumentForm` / `BaseImageForm`
Previously, it was valid to specify an arbitrary model form as the `WAGTAILDOCS_DOCUMENT_FORM_BASE` / `WAGTAILIMAGES_IMAGE_FORM_BASE` settings. This is no longer supported; these forms must now inherit from `wagtail.documents.forms.BaseDocumentForm` and `wagtail.images.forms.BaseImageForm` respectively.