# Wagtail 3.0 release notes - IN DEVELOPMENT

```{contents}
---
local:
depth: 1
---
```

## What's new

### Page editor redesign

Here are other changes related to the redesign:

 * Switch the Wagtail branding font to a system font stack (Steven Steinwand, Paarth Agarwal)
 * Remove most uppercased text styles from admin UI (Paarth Agarwal)
 * Convert all UI code to CSS logical properties for Right-to-Left (RTL) language support (Thibaud Colas)


### Removal of special-purpose field panel types

The panel types `StreamFieldPanel`, `RichTextFieldPanel`, `ImageChooserPanel`, `DocumentChooserPanel` and `SnippetChooserPanel` have been phased out, and can now be replaced with `FieldPanel`. Additionally, `PageChooserPanel` is only required when passing a `page_type` or `can_choose_root`, and can otherwise be replaced with `FieldPanel`. In all cases, `FieldPanel` will now automatically select the most appropriate form element. This feature was developed by Matt Westcott.


### Permission-dependent FieldPanels

[`FieldPanel`](wagtail.admin.panels.FieldPanel) now accepts a `permission` keyword argument to specify that the field should only be available to users with a given permission level. This feature was developed by Matt Westcott and sponsored by Google as part of Wagtail's page editor redevelopment.

### Page descriptions

With every Wagtail Page you are able to add a helpful description text, similar to a `help_text` model attribute. By adding `page_description` to your Page model you'll be adding a short description that can be seen in different places within Wagtail:

```python
class LandingPage(Page):
    
    page_description = "Use this page for converting users"
```

### Other features

 * Upgrade ESLint and Stylelint configurations to latest shared Wagtail configs (Thibaud Colas, Paarth Agarwal)
 * Major updates to frontend tooling; move Node tooling from Gulp to Webpack, upgrade to Node v16 and npm v8, eslint v8, stylelint v14 and others (Thibaud Colas)
 * Change comment headers’ date formatting to use browser APIs instead of requiring a library (LB (Ben Johnston))
 * Lint with flake8-comprehensions and flake8-assertive, including adding a pre-commit hook for these (Mads Jensen, Dan Braghis)
 * Add black configuration and reformat code using it (Dan Braghis)
 * Remove UI code for legacy browser support: polyfills, IE11 workarounds, Modernizr (Thibaud Colas)
 * Remove redirect auto-creation recipe from documentation as this feature is now supported in Wagtail core (Andy Babic)
 * Remove IE11 warnings (Gianluca De Cola)
 * Replace `content_json` `TextField` with `content` `JSONField` in `PageRevision` (Sage Abdullah)
 * Remove `replace_text` management command (Sage Abdullah)
 * Replace `data_json` `TextField` with `data` `JSONField` in `BaseLogEntry` (Sage Abdullah)
 * Remove the legacy Hallo rich text editor as it has moved to an external package (LB (Ben Johnston))
 * Increase the size of checkboxes throughout the UI, and simplify their alignment (Steven Steinwand)
 * Adopt [MyST](https://myst-parser.readthedocs.io/en/latest/) for parsing documentation written in Markdown, replaces recommonmark (LB (Ben Johnston), Thibaud Colas)
 * Installing docs extras requirements in CircleCI so issues with the docs requirements are picked up earlier (Thibaud Colas)
 * Remove core usage of jinjalint and migrate to curlylint to resolve dependency incompatibility issues (Thibaud Colas)
 * Switch focus outlines implementation to `:focus-visible` for cross-browser consistency (Paarth Agarwal)
 * Migrate multiple documentation pages from RST to MD (Vibhakar Solanki, LB (Ben Johnston))
 * Add documentation for defining [custom form validation](modeladmin_custom_clean) on models used in Wagtail's `modelAdmin` (Serafeim Papastefanos)
 * Update `README.md` logo to work for GitHub dark mode (Paarth Agarwal)
 * Avoid an unnecessary page reload when pressing enter within the header search bar (Images, Pages, Documents) (Riley de Mestre)
 * Removed unofficial length parameter on `If-Modified-Since` header in `sendfile_streaming_backend` which was only used by IE (Mariusz Felisiak)
 * Add Pinterest support to the list of default oEmbed providers (Dharmik Gangani)
 * Update Jinja2 template support for Jinja2 3.x (Seb Brown)
 * Add ability for `StreamField` to use `JSONField` to store data, rather than `TextField` (Sage Abdullah)
 * Split up linting / formatting tasks in Makefile into client and server components (Hitansh Shah)
 * Add support for embedding Instagram reels (Luis Nell)
 * Use Django’s JavaScript catalog feature to manage translatable strings in JavaScript (Karl Hobley)
 * Add `trimmed` attribute to all blocktrans tags, so spacing is more reliable in translated strings (Harris Lapiroff)

### Bug fixes

 * Update django-treebeard dependency to 4.5.1 or above (Serafeim Papastefanos)
 * When using `simple_translations` ensure that the user is redirected to the page edit view when submitting for a single locale (Mitchel Cabuloy)
 * When previewing unsaved changes to `Form` pages, ensure that all added fields are correctly shown in the preview (Joshua Munn)
 * When Documents (e.g. PDFs) have been configured to be served inline via `WAGTAILDOCS_CONTENT_TYPES` & `WAGTAILDOCS_INLINE_CONTENT_TYPES` ensure that the filename is correctly set in the `Content-Disposition` header so that saving the files will use the correct filename (John-Scott Atlakson)
 * Improve the contrast of the “Remember me” checkbox against the login page’s background (Steven Steinwand)
 * Group permission rows with custom permissions no longer have extra padding (Steven Steinwand)
 * Make sure the focus outline of checkboxes is fully around the outer border (Steven Steinwand)
 * Consistently set `aria-haspopup="menu"` for all sidebar menu items that have sub-menus (LB (Ben Johnston))
 * Make sure `aria-expanded` is always explicitly set as a string in sidebar (LB (Ben Johnston))
 * Use a button element instead of a link for page explorer menu item, for the correct semantics and behavior (LB (Ben Johnston))
 * Make sure the “Title” column label can be translated in the page chooser and page move UI (Stephanie Cheng Smith)
 * Remove redundant `role="main"` attributes on `<main>` elements causing HTML validation issues (Luis Espinoza)
 * Allow bulk publishing of pages without revisions (Andy Chosak)
 * Stop skipping heading levels in Wagtail welcome page (Jesse Menn)
 * Add missing `lang` attributes to `<html>` elements (James Ray)
 * Add missing translation usage in Workflow templates (Anuja Verma, Saurabh Kumar)


## Upgrade considerations

### Changes to module paths

Various modules of Wagtail have been reorganised, and imports should be updated as follows:

* All modules under `wagtail.core` can now be found under `wagtail` - for example, `from wagtail.core.models import Page` should be changed to `from wagtail.models import Page`
* The `wagtail.tests` module is renamed to `wagtail.test`
* `wagtail.admin.edit_handlers` is renamed to `wagtail.admin.panels`
* `wagtail.contrib.forms.edit_handlers` is renamed to `wagtail.contrib.forms.panels`

These changes can be applied automatically to your project codebase by running the following commands from the project root:

```console
wagtail updatemodulepaths --list  # list the files to be changed without updating them
wagtail updatemodulepaths --diff  # show the changes to be made, without updating files
wagtail updatemodulepaths  # actually update the files
```


### Removed warning in Internet Explorer (IE11)

* IE11 support was officially dropped in Wagtail 2.15, as of this release there will no longer be a warning shown to users of this browser.
* Wagtail is fully compatible with Microsoft Edge, Microsoft’s replacement for Internet Explorer. You may consider using its `IE mode <https://docs.microsoft.com/en-us/deployedge/edge-ie-mode>`_ to keep access to IE11-only sites, while other sites and apps like Wagtail can leverage modern browser capabilities.

### Replaced `content_json` `TextField` with `content` `JSONField` in `PageRevision`

* The `content_json` field in the `PageRevision` model has been renamed to `content`.
* The field now internally uses `JSONField` instead of `TextField`.
* If you have a large number of `PageRevision` objects, running the migrations might take a while.

### Replaced `data_json` `TextField` with `data` `JSONField` in `BaseLogEntry`

* The `data_json` field in the `BaseLogEntry` model has been renamed to `data`.
* The field now internally uses `JSONField` instead of `TextField`.
* The default empty value for the field has been changed from `""` to `{}`.
* This change also affects `BaseLogEntry` subclasses, i.e. `PageLogEntry` and `ModelLogEntry`.
* If you have a large number of objects for these models, running the migrations might take a while.

### Hallo legacy rich text editor has moved to an external package

* Hallo was deprecated in [Wagtail v2.0 (February 2018)](https://docs.wagtail.org/en/stable/releases/2.0.html#new-rich-text-editor) and has had only a minimal level of support since then.
* If you still require Hallo for your Wagtail installation, you will need to install the [Wagtail Hallo editor](https://github.com/wagtail/wagtail-hallo) legacy package.
* We encourage all users of the Hallo editor to take steps to migrate to the new Draftail editor as this external package is unlikely to have ongoing maintenance.
* `window.registerHalloPlugin` will no longer be created on the page editor load, unless the legacy package is installed.

### API changes to panels (EditHandlers)

Various changes have been made to the internal API for defining panel types, previously known as edit handlers. As noted above, the module `wagtail.admin.edit_handlers` has been renamed to `wagtail.admin.panels`, and `wagtail.contrib.forms.edit_handlers` is renamed to `wagtail.contrib.forms.panels`.

Additionally, the base `wagtail.admin.edit_handlers.EditHandler` class has been renamed to `wagtail.admin.panels.Panel`, and `wagtail.admin.edit_handlers.BaseCompositeEditHandler` has been renamed to `wagtail.admin.panels.PanelGroup`.

Template paths have also been renamed accordingly - templates previously within `wagtailadmin/edit_handlers/` are now located under `wagtailadmin/panels/`, and `wagtailforms/edit_handlers/form_responses_panel.html` is now at `wagtailforms/panels/form_responses_panel.html`.

Where possible, third-party packages that implement their own field panel types should be updated to allow using a plain `FieldPanel` instead, in line with Wagtail dropping its own special-purpose field panel types such as `StreamFieldPanel` and `ImageChooserPanel`. The steps for doing this will depend on the package's functionality, but in general:

 * If the panel sets a custom template, your code should instead define [a `Widget` class](https://docs.djangoproject.com/en/stable/ref/forms/widgets/) that produces your desired HTML rendering.
 * If the panel provides a `widget_overrides` method, your code should instead call [`register_form_field_override`](/extending/forms) so that the desired widget is always selected for the relevant model field type.
 * If the panel provides a `get_comparison_class` method, your code should instead call `wagtail.admin.compare.register_comparison_class` to register the comparison class against the relevant model field type.

Within the `Panel` class, the methods `widget_overrides`, `required_fields` and `required_formsets` have been deprecated in favour of a new `get_form_options` method that returns a dict of configuration options to be passed on to the generated form class:

 * Panels that define `required_fields` should instead return this value as a `fields` item in the dict returned from `get_form_options`
 * Panels that define `required_formsets` should instead return this value as a `formsets` item in the dict returned from `get_form_options`
 * Panels that define `widget_overrides` should instead return this value as a `widgets` item in the dict returned from `get_form_options`

The template context for panels derived from `BaseChooserPanel` has changed. `BaseChooserPanel` is deprecated and now functionally identical to `FieldPanel`; as a result, the context variable `is_chosen`, and the variable name given by the panel's `object_type_name` property, are no longer available on the template. The only available variables are now `field` and `show_add_comment_button`. If your template depends on these additional variables, you will need to pass them explicitly by overriding the `render_as_field` method.

### ModelAdmin forms must subclass `WagtailAdminModelForm`

When overriding the `get_form_class` method of a ModelAdmin `CreateView` or `EditView` to pass a custom form class, that form class must now inherit from `wagtail.admin.forms.models.WagtailAdminModelForm`. Passing a plain Django ModelForm subclass is no longer valid.

### Removed the `size` argument of the undocumented `wagtail.utils.sendfile_streaming_backend.was_modified_since` function

-   The `size` argument was used to add a `length` parameter to the HTTP header.
-   This was never part of the HTTP/1.0 and HTTP/1.1 specifications see [RFC7232](https://httpwg.org/specs/rfc7232.html#header.if-modified-since) and existed only as a an unofficial implementation in IE browsers.

### `StreamField`s must explicitly set `use_json_field` argument to `True`/`False`

`StreamField` now requires a `use_json_field` keyword argument that can be set to `True`/`False`. If set to `True`, the field will use `JSONField` as its internal type instead of `TextField`, which will change the data type used on the database and allow you to use `JSONField` lookups and transforms on the `StreamField`. If set to `False`, the field will keep its previous behaviour and no database changes will be made. If set to `None` (the default), the field will keep its previous behaviour and a warning (`RemovedInWagtail50Warning`) will appear.

After setting the keyword argument, make sure to generate and run the migrations for the models.

### Removal of legacy `clean_name` on `AbstractFormField`

-   If you have a project migrating from pre 2.10 to this release and you are using the Wagtail form builder and you have existing form submissions you must first upgrade to at least 2.11. Then run migrations and run the application with your data to ensure that any existing form fields are correctly migrated.
-   In Wagtail 2.10 a `clean_name` field was added to form field models that extend `AbstractFormField` and this initially supported legacy migration of the [Unidecode](https://pypi.org/project/Unidecode/) label conversion.
-   Any new fields created since then will have used the [AnyAscii](https://pypi.org/project/anyascii/) conversion and Unidecode has been removed from the included packages.