===========================================
Wagtail 2.13 release notes - IN DEVELOPMENT
===========================================

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


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

StreamField performance and functionality updates
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The StreamField editing interface has been rebuilt on a client-side rendering model, powered by the `telepath <https://wagtail.github.io/telepath/>`_ library. This provides better performance, increased customisability and UI enhancements including the ability to duplicate blocks. For further background, see the blog post `Telepath - the next evolution of StreamField <https://wagtail.io/blog/telepath/>`_.

This feature was developed by Matt Westcott and Karl Hobley and sponsored by `YouGov <https://yougov.co.uk/>`_, inspired by earlier work on `react-streamfield <https://github.com/wagtail/wagtail-react-streamfield>`_ completed by Bertrand Bordage through the `Wagtail's First Hatch <https://www.kickstarter.com/projects/noripyt/wagtails-first-hatch>`_ crowdfunder.


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

* Support passing ``min_num``, ``max_num`` and ``block_counts`` arguments directly to ``StreamField`` (Haydn Greatnews, Matt Westcott)
* Add the option to set rich text images as decorative, without alt text (Helen Chapman, Thibaud Colas)
* Add support for ``__year`` filter in Elasticsearch queries (Seb Brown)
* Add ``PageQuerySet.defer_streamfields()`` (Andy Babic)
* Utilize ``PageQuerySet.defer_streamfields()`` to improve efficiency in a few key places (Andy Babic)
* Support passing multiple models as arguments to ``type()``, ``not_type()``, ``exact_type()`` and ``not_exact_type()`` methods on ``PageQuerySet`` (Andy Babic)
* Update default attribute copying behaviour of ``Page.get_specific()`` and added the ``copy_attrs_exclude`` option (Andy Babic)
* Update ``PageQueryset.specific(defer=True)`` to only perform a single database query (Andy Babic)
* Switched ``register_setting``, ``register_settings_menu_item`` to use SVG icons (Thibaud Colas)
* Add support to SVG icons for ``SearchArea`` subclasses in ``register_admin_search_area`` (Thibaud Colas)

Bug fixes
~~~~~~~~~

* StreamField required status is now consistently handled by the ``blank`` keyword argument (Matt Westcott)
* Show 'required' asterisks for blocks inside required StreamFields (Matt Westcott)
* Make image chooser "Select format" fields translatable (Helen Chapman, Thibaud Colas)
* Fix pagination on 'view users in a group' (Sagar Agarwal)
* Prevent page privacy menu from being triggered by pressing enter on a char field (Sagar Agarwal)
* Validate host/scheme of return URLs on password authentication forms (Susan Dreher)


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

Updated handling of non-required StreamFields
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The rules for determining whether a StreamField is required (i.e. at least one block must be provided) have been simplified and made consistent with other field types. Non-required fields are now indicated by ``blank=True`` on the ``StreamField`` definition; the default is ``blank=False`` (the field is required). In previous versions, to make a field non-required, it was necessary to define :ref:`a top-level StreamBlock<streamfield_top_level_streamblock>` with ``required=False`` (which applied the validation rule) as well as setting ``blank=True`` (which removed the asterisk from the form field). You should review your use of StreamField to check that ``blank=True`` is used on the fields you wish to make optional.


New client-side implementation for custom StreamField blocks
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For the majority of cases, the new StreamField implementation in this release will be a like-for-like upgrade, and no code changes will be necessary - this includes projects where custom block types have been defined by extending ``StructBlock``, ``ListBlock`` and ``StreamBlock``. However, certain complex customisations may need to be reimplemented to work with the new client-side rendering model:

* If a ``StructBlock`` subclass overrides the ``get_form_context`` method as part of customising the form template, and that method contains logic that causes the returned context to vary depending on the block value, this will no longer work as intended. This is because ``get_form_context`` is now invoked once with the block's default (blank) value in order to construct a template for the client-side rendering to use; previously it was called for each block in the stream. In the new implementation, any Python-side processing that needs to happen on a per-block-value basis can be performed in the block's ``get_form_state`` method; the data returned from that method will then be available in the client-side ``render`` method.
* If ``FieldBlock`` is used to wrap a Django widget with non-standard client-side behaviour - such as requiring a JavaScript function to be called on initialisation, or combining multiple HTML elements such that it is not possible to read or write its data by accessing a single element's ``value`` property - then you will need to supply a JavaScript handler object to define how the widget is rendered and populated, and how to extract data from it.

For further details, see :ref:`custom_streamfield_blocks`.


Switched ``register_setting``, ``register_settings_menu_item`` to use SVG icons
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Setting menu items now use SVG icons by default. For sites reusing built-in Wagtail icons, no changes should be required. For sites using custom font icons, update the menu items’ definition to use the ``classnames`` attribute:

.. code-block:: python

    # With register_setting,
    # Before:
    @register_setting(icon='custom-cog')
    # After:
    @register_setting(icon='', classnames='icon icon-custom-cog')

    # Or with register_settings_menu_item,
    @hooks.register('register_settings_menu_item')
    def register_frank_menu_item():
        # Before:
        return SettingMenuItem(CustomSetting, icon='custom-cog')
        # After:
        return SettingMenuItem(CustomSetting, icon='', classnames='icon icon-custom-cog')