===========================================
Wagtail 2.15 release notes - IN DEVELOPMENT
===========================================

.. contents::
    :local:
    :depth: 1

Wagtail 2.15 is designated a Long Term Support (LTS) release. Long Term Support releases will continue to receive maintenance updates as necessary to address security and data-loss related issues, up until the next LTS release (typically a period of 12 months).


What's new
==========

Other features
~~~~~~~~~~~~~~

 * Add the ability for the page chooser to convert external urls that match a page to internal links, see :ref:`WAGTAILADMIN_EXTERNAL_LINK_CONVERSION` (Jacob Topp-Mugglestone. Sponsored by The Motley Fool)
 * Added "Extending Wagtail" section to documentation (Matt Westcott)
 * Introduced :doc:`template components </extending/template_components>`, a standard mechanism for renderable objects in the admin (Matt Westcott)
 * Support ``min_num`` / ``max_num`` options on ListBlock (Matt Westcott)
 * Added a `background_position_style` property to renditions. This can be used to crop images using its focal point in the browser. See :ref:`rendition_background_position_style` (Karl Hobley)
 * Added a distinct ``wagtail.copy_for_translation`` log action type (Karl Hobley)
 * Add a debug logger around image rendition generation (Jake Howard)
 * Convert Documents and Images to class based views for easier overriding (Matt Westcott)
 * Isolate admin URLs for Documents and Images search listing results with the name `'listing_results'` (Matt Westcott)
 * Removed ``request.is_ajax()`` usage in Documents, Image and Snippet views (Matt Westcott)
 * Simplify generic admin view templates plus ensure ``page_title`` and ``page_subtitle`` are used consistently (Matt Westcott)

Bug fixes
~~~~~~~~~

 * Delete button is now correct colour on snippets and modeladmin listings (Brandon Murch)
 * Ensure that StreamBlock / ListBlock-level validation errors are counted towards error counts (Matt Westcott)
 * InlinePanel add button is now keyboard navigatable (Jesse Menn)
 * Remove redundant 'clear' button from site root page chooser (Matt Westcott)
 * Make ModelAdmin IndexView keyboard-navigable (Saptak Sengupta)
 * Prevent error on refreshing page previews when multiple preview tabs are open (Alex Tomkins)
 * Admin fields and Icon visibility issues in Windows high contrast mode (Dmitrii Faiazov)
 * Add visual separation between the Page Editor's field panels on Windows high contrast mode (Chakita Muttaraju)
 * ``blocks.MultipleChoiceBlock``, ``forms.CheckboxSelectMultiple`` and ``ArrayField`` checkboxes will now stack instead of display inline to align with all other checkboxes fields (Seb Brown)
 * Screen readers can now access login screen field labels (Amy Chan)
 * Admin breadcrumbs home icon now shows for users with access to a subtree only (Stefan Hammer)

Upgrade considerations
======================

Admin homepage panels, summary items and action menu items now use components
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. _template_components_2_15:

Several Wagtail hooks provide a mechanism for passing Python objects to be rendered as HTML inside admin views, and the APIs for these objects have been updated to adopt a common :doc:`template components </extending/template_components>` pattern. The affected objects are:

 * Homepage panels (as registered with the :ref:`construct_homepage_panels` hook)
 * Homepage summary items (as registered with the :ref:`construct_homepage_summary_items` hook)
 * Page action menu items (as registered with the :ref:`register_page_action_menu_item` and :ref:`construct_page_action_menu` hooks)
 * Snippet action menu items (as registered with the :ref:`register_snippet_action_menu_item` and :ref:`construct_snippet_action_menu` hooks)

User code that creates these objects should be updated to follow the component API. This will typically require the following changes:

 * Homepage panels should be made subclasses of ``wagtail.admin.ui.components.Component``, and the ``render(self)`` method should be changed to ``render_html(self, parent_context)``. (Alternatively, rather than defining ``render_html``, it may be more convenient to reimplement it with a template, as per :ref:`creating_template_components`.)
 * Summary item classes can continue to inherit from ``wagtail.admin.site_summary.SummaryItem`` (which is now a subclass of ``Component``) as before, but:

   * Any ``template`` attribute should be changed to ``template_name``;
   * Any place where the ``render(self)`` method is overridden should be changed to ``render_html(self, parent_context)``;
   * Any place where the ``get_context(self)`` method is overridden should be changed to ``get_context_data(self, parent_context)``.

 * Action menu items for pages and snippets can continue to inherit from ``wagtail.admin.action_menu.ActionMenuItem`` and ``wagtail.snippets.action_menu.ActionMenuItem`` respectively - these are now subclasses of ``Component`` - but:

   * Any ``template`` attribute should be changed to ``template_name``;
   * Any ``get_context`` method should be renamed to ``get_context_data``;
   * The ``get_url``, ``is_shown``, ``get_context_data`` and ``render_html`` methods no longer accept a ``request`` parameter. The request object is available in the context dictionary as ``context['request']``.