Extra documentation / release note re the relationship between draft_title and get_admin_display_title

docs/reference/pages/model_reference.rst

@@ -22,6 +22,12 @@ Database fields
 
         Human-readable title of the page.
 
+    .. attribute:: draft_title
+
+        (text)
+
+        Human-readable title of the page, incorporating any changes that have been made in a draft edit (in contrast to the ``title`` field, which for published pages will be the title as it exists in the current published version).
+
     .. attribute:: slug
 
         (text)

docs/releases/1.12.rst

@@ -52,3 +52,16 @@ Old configuration settings for embeds are deprecated
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The configuration settings ``WAGTAILEMBEDS_EMBED_FINDER`` and ``WAGTAILEMBEDS_EMBEDLY_KEY`` have been deprecated in favour of the new ``WAGTAILEMBEDS_FINDERS`` setting. Please see :ref:`configuring_embed_finders` for the new configuration to use.
+
+Custom ``get_admin_display_title`` methods should use ``draft_title``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This release introduces a new ``draft_title`` field on page models, so that page titles as used across the admin interface will correctly reflect any changes that exist in draft. If any of your page models override the ``get_admin_display_title`` method, to customise the display of page titles in the admin, it is recommended that you now update these to base their output on ``draft_title`` rather than ``title``. Alternatively, to preserve backwards compatibility, you can invoke ``super`` on the method, for example:
+
+.. code-block:: python
+
+    def get_admin_display_title(self):
+        return "%(title)s (%(lang)s)" % {
+            'title': super(TranslatablePage, self).get_admin_display_title(),
+            'lang': self.language_code,
+        }

wagtail/wagtailcore/models.py

@@ -671,7 +671,9 @@ class Page(six.with_metaclass(PageBase, AbstractPage, index.Indexed, Clusterable
 
     def get_admin_display_title(self):
         """
-        Return the title for this page as it should appear in the admin backend.
+        Return the title for this page as it should appear in the admin backend;
+        override this if you wish to display extra contextual information about the page,
+        such as language. By default, returns ``draft_title``.
         """
         return self.draft_title