mirror of
https://github.com/wagtail/wagtail.git
synced 2024-12-01 11:41:20 +01:00
375 lines
21 KiB
Markdown
375 lines
21 KiB
Markdown
# Wagtail 5.2 release notes - IN DEVELOPMENT
|
|
|
|
_Unreleased_
|
|
|
|
```{contents}
|
|
---
|
|
local:
|
|
depth: 1
|
|
---
|
|
```
|
|
|
|
## What's new
|
|
|
|
### OpenSearch support
|
|
|
|
[OpenSearch](https://opensearch.org/) is now formally supported as an alternative to Elasticsearch. For configuration details, see [OpenSearch configuration](opensearch). This feature was developed by Matt Westcott.
|
|
|
|
### Other features
|
|
|
|
* Add [`wagtailcache`](wagtailcache) and [`wagtailpagecache`](wagtailpagecache) template tags to ensure previewing Pages or Snippets will not be cached (Jake Howard)
|
|
* Always set help text element ID for form fields with help text in `field.html` template (Sage Abdullah)
|
|
* Move `SnippetViewSet` menu registration mechanism to base `ViewSet` class (Sage Abdullah)
|
|
* Enable reference index tracking for models registered with `ModelViewSet` (Sage Abdullah)
|
|
* When copying a page or creating an alias, copy its view restrictions to the destination (Sandeep Choudhary, Suyash Singh)
|
|
* Support pickling of StreamField values (pySilver)
|
|
* Move `SnippetViewSet` template override mechanism to `ModelViewSet` (Sage Abdullah)
|
|
* Move `SnippetViewSet.list_display` to `ModelViewSet` (Sage Abdullah)
|
|
* Remove `wagtail.publish` log action on aliases when they are created from live source pages or the source page is published (Dan Braghis)
|
|
* Remove `wagtail.unpublish` log action on aliases when source page is unpublished (Dan Braghis)
|
|
* Add compare buttons to workflow dashboard panel (Matt Westcott)
|
|
* Add the ability to use filters and to export listings in generic `IndexView` (Sage Abdullah)
|
|
* Move `list_filter`, `filterset_class`, `search_fields`, `search_backend_name`, `list_export`, `export_filename`, `list_per_page`, and `ordering` from `SnippetViewSet` to `ModelViewSet` (Sage Abdullah)
|
|
* Add default header titles to generic `IndexView` and `CreateView` (Sage Abdullah)
|
|
* Allow overriding `IndexView.export_headings` via `ModelViewSet` (Christer Jensen, Sage Abdullah)
|
|
* Support specifying a `get_object_list` method on `ChooserViewSet` (Matt Westcott)
|
|
* Add `linked_fields` mechanism on chooser widgets to allow choices to be limited by fields on the calling page (Matt Westcott)
|
|
* Add support for merging cells within `TableBlock` with the [`mergedCells` option](table_block_options) (Gareth Palmer)
|
|
* When adding a panel within `InlinePanel`, focus will now shift to that content similar to `StreamField` (Faishal Manzar)
|
|
* Show the full first published at date within a tooltip on the Page status sidebar on the relative date (Rohit Sharma)
|
|
* Extract generic breadcrumbs functionality from page breadcrumbs (Sage Abdullah)
|
|
* Add support for `placement` in `human_readable_date` the tooltip template tag (Rohit Sharma)
|
|
* Add breadcrumbs to generic model views (Sage Abdullah)
|
|
* Support passing extra context variables via the `{% component %}` tag (Matt Westcott)
|
|
* Allow subclasses of `PagesAPIViewSet` override default Page model via the `model` attribute (Neeraj Yetheendran, Herbert Poul)
|
|
* Allow `ModelViewSet` to be used with models that have non-integer primary keys (Sage Abdullah)
|
|
* Add the ability to set an external link/text for promoted search result entries (TopDevPros, Brad Busenius)
|
|
* Add support for subject and body in the Email link chooser form (TopDevPros, Alexandre Joly)
|
|
* Extract generic `HistoryView` from snippets and add it to `ModelViewSet` (Sage Abdullah)
|
|
* Add generic `UsageView` to `ModelViewSet` (Sage Abdullah)
|
|
* Add the ability to define listing buttons on generic `IndexView` (Sage Abdullah)
|
|
|
|
### Bug fixes
|
|
|
|
* Ensure that StreamField's `FieldBlock`s correctly set the `required` and `aria-describedby` attributes (Storm Heg)
|
|
* Avoid an error when the moderation panel (admin dashboard) contains both snippets and private pages (Matt Westcott)
|
|
* When deleting collections, ensure the collection name is correctly shown in the success message (LB (Ben) Johnston)
|
|
* Filter out comments on Page editing counts that do not correspond to a valid field / block path on the page such as when a field has been removed (Matt Westcott)
|
|
* Allow `PublishMenuItem` to more easily support overriding its label via `construct_page_action_menu` (Sébastien Corbin)
|
|
* Allow locale selection when creating a page at the root level (Sage Abdullah)
|
|
* Ensure the admin login template correctly displays all `non_fields_errors` for any custom form validation (Sébastien Corbin)
|
|
* Ensure 'mark as active' label in workflow bulk action set active form can be translated (Rohit Sharma)
|
|
* Ensure the panel title for a user's settings correctly reflects the `WAGTAIL_EMAIL_MANAGEMENT_ENABLED` setting by not showing 'email' if disabled (Omkar Jadhav)
|
|
* Update Spotify oEmbed provider URL parsing to resolve correctly (Dhrűv)
|
|
|
|
### Documentation
|
|
|
|
* Document `WAGTAILADMIN_BASE_URL` on "Integrating Wagtail into a Django project" page (Shreshth Srivastava)
|
|
* Replace incorrect screenshot for authors listing on tutorial (Shreshth Srivastava)
|
|
* Add documentation for building non-model-based choosers using the _queryish_ library (Matt Westcott)
|
|
* Fix incorrect tag library import on focal points example (Hatim Makki Hoho)
|
|
* Add reminder about including your custom Draftail feature in any overridden `WAGTAILADMIN_RICH_TEXT_EDITORS` setting (Charlie Sue)
|
|
* Mention the need to install `python3-venv` on Ubuntu (Brian Mugo)
|
|
|
|
### Maintenance
|
|
|
|
* Fix snippet search test to work on non-fallback database backends (Matt Westcott)
|
|
* Update Eslint, Prettier & Jest npm packages (LB (Ben) Johnston)
|
|
* Add npm scripts for TypeScript checks and formatting SCSS files (LB (Ben) Johnston)
|
|
* Run tests in parallel in some of the CI setup (Sage Abdullah)
|
|
* Remove unused WorkflowStatus view, urlpattern, and workflow-status.js (Storm Heg)
|
|
* Add support for options/attrs in Telepath widgets so that attrs render on the created DOM (Storm Heg)
|
|
* Update pre-commit hooks to be in sync with latest changes to Eslint & Prettier for client-side changes (Storm Heg)
|
|
* Add `WagtailTestUtils.get_soup()` method for testing HTML content (Storm Heg, Sage Abdullah)
|
|
* Allow `ViewSet` subclasses to customise `url_prefix` and `url_namespace` logic (Matt Westcott)
|
|
* Simplify `SnippetViewSet` registration code (Sage Abdullah)
|
|
* Rename groups `IndexView.results_template_name` to `results.html` (Sage Abdullah)
|
|
* Migrate form submission listing checkbox toggling to the shared `w-bulk` Stimulus implementation (LB (Ben) Johnston)
|
|
* Allow viewsets to define a common set of view kwargs (Matt Westcott)
|
|
* Migrate the editor unsaved messages popup to be driven by Stimulus using the shared `w-message` controller (LB (Ben) Johnston, Hussain Saherwala)
|
|
* Do not use jest inside `stubs.js` to prevent Storybook from crashing (LB (Ben) Johnston)
|
|
* Refactor snippets templates to reuse the shared `slim_header.html` template (Sage Abdullah)
|
|
* Refactor `slim_header.html` template to reduce code duplication (Sage Abdullah)
|
|
* Upgrade Willow to v1.6.2 to support MIME type data without reliance on `imghdr` (Jake Howard)
|
|
* Replace `imghdr` with Willow's built-in MIME type detection (Jake Howard)
|
|
* Migrate all other `data-tippy` HTML attribute usage to the Stimulus data-*-value attributes for w-tooltip & w-dropdown (Subhajit Ghosh, LB (Ben) Johnston)
|
|
* Replace `@total_ordering` usage with comparison functions implementation (Virag Jain)
|
|
* Replace `<script type="text/django-form-template"><-/script>` template approach with HTML `template` elements in InlinePanel and expanding formset (Mansi Gundre, Subhajit Ghosh, LB (Ben) Johnston)
|
|
* Refactor side panels code for better reuse in pages and snippets (Sage Abdullah)
|
|
* Deprecate legacy URL redirects in `ModelViewSet` and `SnippetViewSet` (Sage Abdullah)
|
|
* Simplify code for registering page listing action buttons (Matt Westcott)
|
|
* Removed the unused, legacy, Wagtail userbar views set up for an old iframe approach (Sage Abdullah)
|
|
* Optimise `lru_cache` usage (Jake Howard)
|
|
* Implement `date_since`` in `get_most_popular`` inside `search_promotions.models.Query (TopDevPros)
|
|
* Refactor generic view subclasses to better reuse the generic templates and breadcrumbs (Sage Abdullah)
|
|
* Adopt consistent `classname` (not `classnames`) attributes for all `MenuItem` usage, including deprecation warnings (LB (Ben) Johnston)
|
|
* Deprecate `context` argument of `construct_snippet_listing_buttons` hook (Sage Abdullah)
|
|
|
|
|
|
## Upgrade considerations - changes affecting all projects
|
|
|
|
### Removal of `imghdr` and upgrade to `Willow`
|
|
|
|
[`imghdr`](https://docs.python.org/3/library/imghdr.html) is deprecated, and will be removed in Python 3.13.
|
|
|
|
Wagtail now uses the Willow feature of providing the image MIME type, which uses the [`filetype`](https://pypi.org/project/filetype/) package.
|
|
|
|
### Adoption of `classname` convention for `MenuItem` related classes and hooks
|
|
|
|
Wagtail `MenuItem` and menu hooks have been updated to use the more consistent naming of `classname` (singular) instead of `classnames` (plural), a convention that started in Wagtail 4.2.
|
|
|
|
The current `classnames` keyword argument naming will be supported, but will trigger a deprecation warning. Support for this variant will be removed in a future release.
|
|
|
|
The following classes will adopt this new convention.
|
|
|
|
- `admin.menu.MenuItem`
|
|
- `admin.ui.sidebar.ActionMenuItem`
|
|
- `admin.ui.sidebar.LinkMenuItem`
|
|
- `admin.ui.sidebar.PageExplorerMenuItem`
|
|
- `contrib.settings.registry.SettingMenuItem`
|
|
|
|
The following hooks usage may be impacted if `classnames` were used when generating menu items.
|
|
|
|
- `register_admin_menu_item`
|
|
- `register_settings_menu_item`
|
|
|
|
### Example
|
|
|
|
```python
|
|
from django.urls import reverse
|
|
|
|
from wagtail import hooks
|
|
from wagtail.admin.menu import MenuItem
|
|
|
|
@hooks.register('register_admin_menu_item')
|
|
def register_frank_menu_item():
|
|
return MenuItem(
|
|
'Frank',
|
|
reverse('frank'),
|
|
icon_name='folder-inverse',
|
|
order=10000,
|
|
classname="highlight-menu" # not classnames=...
|
|
)
|
|
```
|
|
|
|
## Upgrade considerations - deprecation of old functionality
|
|
|
|
## Upgrade considerations - changes affecting Wagtail customisations
|
|
|
|
### Edit and delete URLs in `ModelViewSet` changed to allow non-integer primary keys
|
|
|
|
To accommodate models with non-integer primary keys, the URL patterns for the edit and delete views in {class}`~wagtail.admin.viewsets.model.ModelViewSet` have been changed.
|
|
|
|
Relative to the viewset's {attr}`~wagtail.admin.viewsets.base.ViewSet.url_prefix`, the following changes have been made:
|
|
- The edit URL pattern has been changed from `<int:pk>/` to `edit/<str:pk>/`
|
|
- The delete URL pattern has been changed from `<int:pk>/delete/` to `delete/<str:pk>/`
|
|
|
|
If you use {func}`~django.urls.reverse` with {meth}`~wagtail.admin.viewsets.base.ViewSet.get_url_name` to generate the URLs for these views, no changes are needed. However, if you have hard-coded these URLs in your code, you will need to update them to match the new patterns.
|
|
|
|
Redirects for the legacy URLs are in place for backwards compatibility, but will be removed in a future release.
|
|
|
|
The URLs for snippets underwent similar changes in Wagtail 2.14. The redirects for the legacy URLs in {class}`~wagtail.snippets.views.snippets.SnippetViewSet` have now been marked for removal in a future release.
|
|
|
|
### `ModelViewSet` automatically registers the model to the reference index
|
|
|
|
Models that are registered with a `ModelViewSet` now have reference index tracking enabled by default. This means that you no longer need to call `ReferenceIndex.register_model()` in your app's `ready()` method for such models. If this is undesired, you can disable it by setting {attr}`~wagtail.admin.viewsets.model.ModelViewSet.add_to_reference_index` to `False` on the `ModelViewSet` subclass. For more details, see [](managing_the_reference_index).
|
|
|
|
### Groups `IndexView.results_template_name` renamed from `results.html` to `index_results.html`
|
|
|
|
The `IndexView`'s `results_template_name` attribute in the `GroupViewSet` has been renamed from `wagtailusers/groups/results.html` to `wagtailusers/groups/index_results.html` for consistency with the other viewsets. If you have customised or extended the template, e.g. for [](customising_group_views), you will need to rename it to match the new name.
|
|
|
|
### Breadcrumbs class name has changed
|
|
|
|
If using custom styling for the breadcrumbs, this class has changed from singular to plural for a more intuitive class.
|
|
|
|
| Old | New |
|
|
| ---------------- | ----------------- |
|
|
| `'w-breadcrumb'` | `'w-breadcrumbs'` |
|
|
|
|
### Breadcrumbs now use different data attributes and events
|
|
|
|
The undocumented JavaScript implementation for the header breadcrumbs component has been migrated to a Stimulus controller and now uses different data attributes.
|
|
|
|
This may impact custom header implementations that relied on the previous approach, custom breadcrumbs that did not use `breadcrumbs` and require the expand/collapse behaviour may be impacted.
|
|
|
|
#### Events
|
|
|
|
| Old | New |
|
|
| -------------------------------- | ------------------------ |
|
|
| `'wagtail:breadcrumbs-expand'` | `'w-breadcrumbs:opened'` |
|
|
| `'wagtail:breadcrumbs-collapse'` | `'w-breadcrumbs:closed'` |
|
|
|
|
#### Data attributes
|
|
|
|
| Old | New |
|
|
| ------------------------- | ------------------------------------------------------------------------------------------------------ |
|
|
| `data-breadcrumb-next` | `data-controller="w-breadcrumbs"` |
|
|
| `data-toggle-breadcrumbs` | `data-w-breadcrumbs-target="toggle" data-action="w-breadcrumbs#toggle mouseenter->w-breadcrumbs#peek"` |
|
|
| `data-breadcrumb-item` | `data-w-breadcrumbs-target="content"` |
|
|
|
|
Note that the root DOM element also includes a set of additional data attributes to function as the breadcrumbs:
|
|
|
|
```
|
|
data-controller="w-breadcrumbs"
|
|
data-action="keyup.esc@document->w-breadcrumbs#close w-breadcrumbs:open@document->w-breadcrumbs#open w-breadcrumbs:close@document->w-breadcrumbs#close"
|
|
data-w-breadcrumbs-close-icon-class="icon-cross"
|
|
data-w-breadcrumbs-closed-value="true"
|
|
data-w-breadcrumbs-open-icon-class="icon-breadcrumb-expand"
|
|
data-w-breadcrumbs-opened-content-class="w-max-w-4xl"
|
|
data-w-breadcrumbs-peek-target-value="header"
|
|
```
|
|
|
|
### `window.updateFooterSaveWarning` global util removed
|
|
|
|
The undocumented global util `window.updateFooterSaveWarning` has been removed, this is part of the footer 'unsaved' messages toggling behaviour on page forms.
|
|
This behaviour has now moved to a Stimulus controller and leverages DOM events instead. Calling this function will do nothing and in a future release will throw an error.
|
|
|
|
You can implement roughly the equivalent functionality with this JavaScript function, however, this will not be guaranteed to work in future releases.
|
|
|
|
```js
|
|
window.updateFooterSaveWarning = (formDirty, commentsDirty) => {
|
|
if (!formDirty && !commentsDirty) {
|
|
document.dispatchEvent(new CustomEvent('w-unsaved:clear'));
|
|
} else {
|
|
const [type] = [
|
|
formDirty && commentsDirty && 'all',
|
|
commentsDirty && 'comments',
|
|
formDirty && 'edits',
|
|
].filter(Boolean);
|
|
document.dispatchEvent(new CustomEvent('w-unsaved:add', { detail: { type } }));
|
|
}
|
|
};
|
|
```
|
|
|
|
### Snippets templates refactored to reuse the shared `slim_header.html` template
|
|
|
|
The templates for the snippets views have been refactored to reuse the shared `slim_header.html` template. If you have customised or extended the templates, e.g. for [](wagtailsnippets_custom_admin_views), you will need to update them to match the new structure. As a result, the following templates have been removed:
|
|
|
|
- `wagtailsnippets/snippets/headers/_base_header.html`
|
|
- `wagtailsnippets/snippets/headers/create_header.html`
|
|
- `wagtailsnippets/snippets/headers/edit_header.html`
|
|
- `wagtailsnippets/snippets/headers/history_header.html`
|
|
- `wagtailsnippets/snippets/headers/list_header.html`
|
|
- `wagtailsnippets/snippets/headers/usage_header.html`
|
|
|
|
In most cases, the usage of those templates can be replaced with the `wagtailadmin/shared/headers/slim_header.html` template. Refer to the snippets views and templates code for more details.
|
|
|
|
### `dropdown` template tag argument `toggle_tippy_offset` renamed to `toggle_tooltip_offset`
|
|
|
|
The naming conventions for `tippy` related attributes have been updated to align with the generic `tooltip` naming.
|
|
|
|
If you are using the undocumented dropdown template tag with the offset arg, this will need to be updated.
|
|
|
|
| Old | New |
|
|
| ------------------------------------------------------------------ | -------------------------------------------------------------------- |
|
|
| `{% dropdown toggle_tippy_offset="[0, -2]" %}...{% enddropdown %}` | `{% dropdown toggle_tooltip_offset="[0, -2]" %}...{% enddropdown %}` |
|
|
|
|
### `escapescript` template tag and `escape_script` functions are deprecated
|
|
|
|
As of this release, the undocumented `coreutils.escape_script` util and `escapescript` template tag will no longer be supported.
|
|
|
|
This was used to provide a way for HTML template content in IE11, which is no longer supported, and was non-compliant with CSP support.
|
|
|
|
The current approach will trigger a deprecation warning and will be removed in a future release.
|
|
|
|
#### Old
|
|
|
|
```html+django
|
|
{% load wagtailadmin_tags %}
|
|
<script type="text/django-form-template" id="id_{{ formset.prefix }}-EMPTY_FORM_TEMPLATE">
|
|
{% escapescript %}
|
|
<div>Widget template content</div>
|
|
<script src="/js/my-widget.js"></script>
|
|
{% endescapescript %}
|
|
</script>
|
|
```
|
|
|
|
#### New
|
|
|
|
Use the HTML [`template`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/template) element to avoid content from being parsed by the browser on load.
|
|
|
|
```html+django
|
|
<template id="id_{{ formset.prefix }}-EMPTY_FORM_TEMPLATE">
|
|
<div>Widget template content</div>
|
|
<script src="/js/my-widget.js"></script>
|
|
</template>
|
|
```
|
|
|
|
### `BaseSidePanels`, `PageSidePanels` and `SnippetSidePanels` classes are removed
|
|
|
|
The `BaseSidePanels`, `PageSidePanels` and `SnippetSidePanels` classes that were used to combine the side panels (i.e. status, preview and comments side panels) have been removed. Each side panel is now instantiated directly in the view. The `wagtail.admin.ui.components.MediaContainer` class can be used to combine the [`Media`](django:topics/forms/media) objects for the side panels.
|
|
|
|
The `BasePreviewSidePanel`, `PagePreviewSidePanel` and `SnippetPreviewSidePanel` classes have been replaced with the consolidated `PreviewSidePanel` class.
|
|
|
|
The `BaseStatusSidePanel` class has been renamed to `StatusSidePanel`.
|
|
|
|
If you use these classes in your code, you will need to update your code to instantiate the side panels directly in the view.
|
|
|
|
For example, if you have the following code:
|
|
|
|
```python
|
|
from wagtail.admin.ui.side_panels import PageSidePanels
|
|
|
|
|
|
def my_view(request):
|
|
...
|
|
|
|
side_panels = PageSidePanels(
|
|
request,
|
|
page.get_latest_revision_as_object(),
|
|
show_schedule_publishing_toggle=False,
|
|
live_page=page,
|
|
scheduled_page=page.get_scheduled_revision_as_object(),
|
|
in_explorer=False,
|
|
preview_enabled=True,
|
|
comments_enabled=False,
|
|
)
|
|
|
|
return render(
|
|
request,
|
|
template_name,
|
|
{"page": page, "side_panels": side_panels, "media": side_panels.media},
|
|
)
|
|
```
|
|
|
|
Update it to the following:
|
|
|
|
```python
|
|
from wagtail.admin.ui.components import MediaContainer
|
|
from wagtail.admin.ui.side_panels import PageStatusSidePanel, PreviewSidePanel
|
|
|
|
|
|
def my_view(request):
|
|
...
|
|
|
|
side_panels = [
|
|
PageStatusSidePanel(
|
|
page,
|
|
request,
|
|
show_schedule_publishing_toggle=False,
|
|
live_object=page,
|
|
scheduled_object=page.get_scheduled_revision_as_object(),
|
|
locale=page.locale,
|
|
translations=translations,
|
|
),
|
|
PreviewSidePanel(
|
|
page,
|
|
request,
|
|
preview_url=reverse("wagtailadmin_pages:preview_on_edit", args=[page.id]),
|
|
),
|
|
]
|
|
side_panels = MediaContainer(side_panels)
|
|
|
|
return render(
|
|
request,
|
|
template_name,
|
|
{"page": page, "side_panels": side_panels, "media": side_panels.media},
|
|
)
|
|
```
|
|
|
|
### `construct_snippet_listing_buttons` hook no longer accepts a `context` argument
|
|
|
|
The [`construct_snippet_listing_buttons`](construct_snippet_listing_buttons) hook no longer accepts a `context` argument. If you have implemented this hook, you will need to remove the `context` argument from your implementation. If you need to access values computed by the view, you'll need to override the {attr}`~wagtail.snippets.views.snippets.SnippetViewSet.index_view_class` with a custom `IndexView` subclass. The `get_list_buttons` and `get_list_more_buttons` methods in particular may be overridden to customise the buttons on the listing.
|
|
|
|
Defining a function for this hook that accepts the `context` argument will raise a warning, and the function will receive an empty dictionary (`{}`) as the `context`. Support for defining the `context` argument will be completely removed in a future Wagtail release.
|