Update docs to cover use of components in homepage panels / summary items

docs/extending/template_components.md

@@ -17,7 +17,9 @@ A (possibly empty) :doc:`form media <django:topics/forms/media>` object defining
    Any object implementing this API can be considered a valid component; it does not necessarily have to inherit from the ``Component`` class described below, and user code that works with components should not assume this (for example, it must not use ``isinstance`` to check whether a given value is a component).
 ```
 
-
+```eval_rst
+.. _creating_template_components:
+```
 ## Creating components
 
 The simplest way to create a component is to define a subclass of `wagtail.admin.ui.components.Component` and specify a `template_name` attribute on it. The rendered template will then be used as the component's HTML representation:

docs/reference/hooks.rst

@@ -113,18 +113,19 @@ Hooks for building new areas of the admin interface (alongside pages, images, do
 ``construct_homepage_panels``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-  Add or remove panels from the Wagtail admin homepage. The callable passed into this hook should take a ``request`` object and a list of ``panels``, objects which have a ``render()`` method returning a string. The objects also have an ``order`` property, an integer used for ordering the panels. The default panels use integers between ``100`` and ``300``. Hook functions should modify the ``panels`` list in-place as required.
+  Add or remove panels from the Wagtail admin homepage. The callable passed into this hook should take a ``request`` object and a list of panel objects, and should modify this list in-place as required. Panel objects are :doc:`components </extending/template_components>` with an additional ``order`` property, an integer that determines the panel's position in the final ordered list. The default panels use integers between ``100`` and ``300``.
 
   .. code-block:: python
 
     from django.utils.safestring import mark_safe
 
+    from wagtail.admin.ui.components import Component
     from wagtail.core import hooks
 
-    class WelcomePanel:
+    class WelcomePanel(Component):
         order = 50
 
-        def render(self):
+        def render_html(self, parent_context):
             return mark_safe("""
             <section class="panel summary nice-padding">
               <h3>No, but seriously -- welcome to the admin homepage.</h3>
@@ -141,7 +142,19 @@ Hooks for building new areas of the admin interface (alongside pages, images, do
 ``construct_homepage_summary_items``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-  Add or remove items from the 'site summary' bar on the admin homepage (which shows the number of pages and other object that exist on the site). The callable passed into this hook should take a ``request`` object and a list of ``SummaryItem`` objects to be modified as required. These objects have a ``render()`` method, which returns an HTML string, and an ``order`` property, which is an integer that specifies the order in which the items will appear.
+  Add or remove items from the 'site summary' bar on the admin homepage (which shows the number of pages and other object that exist on the site). The callable passed into this hook should take a ``request`` object and a list of summary item objects, and should modify this list in-place as required. Summary item objects are instances of ``wagtail.admin.site_summary.SummaryItem``, which extends :ref:`the Component class <creating_template_components>` with the following additional methods and properties:
+
+  .. method:: SummaryItem(request)
+
+    Constructor; receives the request object its argument
+
+  .. attribute:: order
+
+    An integer that specifies the item's position in the sequence.
+
+  .. method:: is_shown()
+
+    Returns a boolean indicating whether the summary item should be shown on this request.
 
 
 .. _construct_main_menu:

docs/releases/2.15.rst

@@ -39,3 +39,14 @@ Bug fixes
 
 Upgrade considerations
 ======================
+
+Admin homepage panels and summary items now use components
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Admin homepage panels (as registered with the :ref:`construct_homepage_panels` hook) and summary items (as registered with :ref:`construct_homepage_summary_items`) have been updated to adopt the :doc:`template components </extending/template_components>` pattern. User code that creates these object should be updated to ensure that they follow the component API. This will typically require the following changes:
+
+ * Classes defined for use as homepage panels should be made subclasses of ``wagtail.admin.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)``.