==========================================
Wagtail 1.2 release notes - IN DEVELOPMENT
==========================================

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


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

Site settings module
~~~~~~~~~~~~~~~~~~~~

Wagtail now includes a contrib module (previously available as the `wagtailsettings <https://pypi.python.org/pypi/wagtailsettings/>`_ package) to allow administrators to edit site-specific settings.

See: :doc:`/reference/contrib/settings`


Jinja2 support
~~~~~~~~~~~~~~

The core templatetags (``pageurl``, ``slugurl``, ``image``, ``richtext`` and ``wagtailuserbar``) are now compatible with Jinja2 so it's now possible to use Jinja2 as the template engine for your Wagtail site.

Note that the variable name ``self`` is reserved in Jinja2, and so Wagtail now provides alternative variable names where ``self`` was previously used: ``page`` to refer to page objects, and ``value`` to refer to StreamField blocks. All code examples in this documentation have now been updated to use the new variable names, for compatibility with Jinja2; however, users of the default Django template engine can continue to use ``self``.

See: :doc:`/advanced_topics/jinja2`


Search API improvements
~~~~~~~~~~~~~~~~~~~~~~~

Wagtail's image and document models now provide a ``search`` method on their QuerySets, making it easy to perform searches on filtered data sets. In addition, search methods now accept two new keyword arguments:

 * ``operator``, to determine whether multiple search terms will be treated as 'or' (any term may match) or 'and' (all terms must match);
 * ``order_by_relevance``, set to True (the default) to order by relevance or False to preserve the QuerySet's original ordering.

See: :ref:`wagtailsearch_searching`


``max_num`` and ``min_num`` parameters on inline panels
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Inline panels now accept the optional parameters ``max_num`` and ``min_num``, to specify the maximum / minimum number of child items that must exist in order for the page to be valid.

See: :ref:`inline_panels`


``get_context`` on StreamField blocks
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

StreamField blocks now :ref:`provide a get_context method <streamfield_get_context>` that can be overridden to pass additional variables to the block's template.


Browsable API
~~~~~~~~~~~~~

The Wagtail API now incorporates the browsable front-end provided by Django REST Framework. Note that this must be enabled by adding ``'rest_framework'`` to your project's ``INSTALLED_APPS`` setting.


Minor features
~~~~~~~~~~~~~~

 * WagtailRedirectMiddleware can now ignore the query string if there is no redirect that exactly matches it
 * Order of URL parameters now ignored by redirect middleware
 * Added SQL Server compatibility to image migration
 * Added classnames to Wagtail rich text editor buttons to aid custom styling
 * Simplified body_class in default homepage template
 * page_published signal now called with the revision object that was published
 * Added a favicon to the admin interface, customisable by overriding the ``branding_favicon`` block (see :ref:`custom_branding`).
 * Added spinner animations to long-running form submissions
 * The EMBEDLY_KEY setting has been renamed to WAGTAILEMBEDS_EMBEDLY_KEY
 * StreamField blocks are now added automatically, without showing the block types menu, if only one block type exists (Alex Gleason)
 * The ``first_published_at`` and ``latest_revision_created_at`` fields on page models are now available as filter fields on search queries
 * Wagtail admin now standardises on a single thumbnail image size, to reduce the overhead of creating multiple renditions
 * Rich text fields now strip out HTML comments
 * Page editor form now sets ``enctype="multipart/form-data"`` as appropriate, allowing FileField to be used on page models (Petr Vacha)
 * Explorer navigation menu on a completely empty page tree now takes you to the root level, rather than doing nothing

Bug fixes
~~~~~~~~~

 * Page slugs are no longer auto-updated from the page title if the page is already published
 * Deleting a page permission from the groups admin UI does not immediately submit the form
 * Wagtail userbar is shown on pages that do not pass a ``page`` variable to the template (e.g. because they override the ``serve`` method)
 * ``request.site`` now set correctly on page preview when the page is not in the default site
 * Project template no longer raises a deprecation warning (Maximilian Stauss)
 * ``PageManager.sibling_of(page)`` and ``PageManager.not_sibling_of(page)`` now default to inclusive (i.e. ``page`` is considered a sibling of itself), for consistency with other sibling methods
 * The "view live" button displayed after publishing a page now correctly reflects any changes made to the page slug (Ryan Pineo)
 * API endpoints now accept and ignore the ``_`` query parameter used by jQuery for cache-busting
 * Page slugs are no longer cut off when Unicode characters are expanded into multiple characters (Sævar Öfjörð Magnússon)
 * Searching a specific page model while filtering it by either ID or tree position no longer raises an error (Ashia Zawaduk)
 * Scrolling an over-long explorer menu no longer causes white background to show through (Alex Gleason)
 * Removed jitter when hovering over StreamField blocks (Alex Gleason)
 * Non-ASCII email addresses no longer throw errors when generating Gravatar URLs (Denis Voskvitsov, Kyle Stratis)

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

``PageManager.sibling_of(page)`` and ``PageManager.not_sibling_of(page)`` have changed behaviour
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In previous versions of Wagtail, the ``sibling_of`` and ``not_sibling_of`` methods behaved inconsistently depending on whether they were called on a manager (e.g. ``Page.objects.sibling_of(some_page)`` or ``EventPage.objects.sibling_of(some_page)``) or a QuerySet (e.g. ``Page.objects.all().sibling_of(some_page)`` or ``EventPage.objects.live().sibling_of(some_page)``).

Previously, the manager methods behaved as *exclusive* by default; that is, they did not count the passed-in page object as a sibling of itself:

.. code-block:: python

    >>> event_1 = EventPage.objects.get(title='Event 1')
    >>> EventPage.objects.sibling_of(event_1)
    [<EventPage: Event 2>]  # OLD behaviour: Event 1 is not considered a sibling of itself


This has now been changed to be *inclusive* by default; that is, the page is counted as a sibling of itself:

.. code-block:: python

    >>> event_1 = EventPage.objects.get(title='Event 1')
    >>> EventPage.objects.sibling_of(event_1)
    [<EventPage: Event 1>, <EventPage: Event 2>]  # NEW behaviour: Event 1 is considered a sibling of itself


If the call to ``sibling_of`` or ``not_sibling_of`` is chained after another QuerySet method - such as ``all()``, ``filter()`` or ``live()`` - behaviour is unchanged; this behaves as *inclusive*, as it did in previous versions:

.. code-block:: python

    >>> event_1 = EventPage.objects.get(title='Event 1')
    >>> EventPage.objects.all().sibling_of(event_1)
    [<EventPage: Event 1>, <EventPage: Event 2>]  # OLD and NEW behaviour


If your project includes queries that rely on the old (exclusive) behaviour, this behaviour can be restored by adding the keyword argument ``inclusive=False``:

.. code-block:: python

    >>> event_1 = EventPage.objects.get(title='Event 1')
    >>> EventPage.objects.sibling_of(event_1, inclusive=False)
    [<EventPage: Event 2>]  # passing inclusive=False restores the OLD behaviour


``Image.search`` and ``Document.search`` methods are deprecated
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The ``Image.search`` and ``Document.search`` methods have been deprecated in favour of the new QuerySet-based search mechanism - see :ref:`wagtailsearch_images_documents_custom_models`. Code using the old ``search`` methods should be updated to search on QuerySets instead; for example:

.. code-block:: python

    Image.search("Hello", filters={'uploaded_by_user': user})

can be rewritten as:

.. code-block:: python

    Image.objects.filter(uploaded_by_user=user).search("Hello")


Wagtail API requires adding ``rest_framework`` to INSTALLED_APPS
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you have the Wagtail API (``wagtail.contrib.wagtailapi``) enabled, you must now add ``'rest_framework'`` to your project's ``INSTALLED_APPS`` setting. In the current version the API will continue to function without this app, but the browsable front-end will not be available; this ability will be dropped in a future release.