Add complete report example

docs/advanced_topics/adding_reports.rst

@@ -5,7 +5,8 @@ Reports are views with listings of pages matching a specific query. They can als
 They are found in the `Reports` submenu: by default, the `Locked Pages` report is provided, allowing an overview of locked pages on the site.
 
 It is possible to create your own custom reports in the Wagtail admin. To do this, you will need to subclass
-``wagtail.admin.views.reports.ReportView``, which provides basic listing and spreadsheet export functionality:
+``wagtail.admin.views.reports.ReportView``, which provides basic listing and spreadsheet export functionality.
+For this example, we'll add a report which shows any pages with unpublished changes.
 
 .. code-block:: python
 
@@ -14,7 +15,7 @@ It is possible to create your own custom reports in the Wagtail admin. To do thi
     from wagtail.admin.views.report.ReportView
 
 
-    class CustomReportView(ReportView):
+    class UnpublishedChangesReportView(ReportView):
         pass
 
 
@@ -25,20 +26,20 @@ The most important attributes and methods to customise to define your report are
 
 .. method:: get_queryset(self)
 
-This retrieves the queryset of pages for your report. For example, if you wanted a report on all pages shown in menus:
+This retrieves the queryset of pages for your report. For our example:
 
 .. code-block:: python
 
     # <project>/views.py
 
-    from wagtail.admin.views.report.ReportView
+    from wagtail.admin.views.reports import ReportView
     from wagtail.core.models import Page
 
 
-    class MenuReportView(ReportView):
+    class UnpublishedChangesReportView(ReportView):
         
         def get_queryset(self):
-            return Page.objects.in_menu()
+            return Page.objects.filter(has_unpublished_changes=True)
 
 .. attribute:: template_name
 
@@ -46,19 +47,22 @@ This retrieves the queryset of pages for your report. For example, if you wanted
 
 The template used to render your report. By default, this is ``"wagtailadmin/reports/base_report.html"``,
 which has a listing based on the explorer views, displaying action buttons, as well as the title,
-time of the last update, status, and specific type of any pages.
+time of the last update, status, and specific type of any pages. In this example, we'll change this
+to a new template in a later section.
 
 .. attribute:: title
 
 (string)
 
-The name of your report, which will be displayed in the header.
+The name of your report, which will be displayed in the header. For our example, we'll set it to
+``"Pages with unpublished changes"``.
 
-.. attribute:: ReportView.header_icon
+.. attribute:: header_icon
 
 (string)
 
-The name of the icon, using the standard Wagtail icon names. For example, the locked pages view uses ``"locked"``.
+The name of the icon, using the standard Wagtail icon names. For example, the locked pages view uses ``"locked"``,
+and for our example report, we'll set it to ``'doc-empty-inverse'``.
 
 Spreadsheet exports
 -------------------
@@ -69,6 +73,9 @@ Spreadsheet exports
 
 A list of the fields/attributes for each model which are exported as columns in the spreadsheet view. By default,
 this is identical to the listing fields: the title, time of the last update, status, and specific type of any pages.
+For our example, we might want to know when the page was last published, so we'll set ``list_export`` as follows:
+
+``list_export = ReportView.list_export + ['last_published_at']``
 
 .. attribute:: export_heading_overrides
 
@@ -76,7 +83,10 @@ this is identical to the listing fields: the title, time of the last update, sta
 
 A dictionary of any fields/attributes in ``list_export`` for which you wish to manually specify a heading for the spreadsheet
 column, and their headings. If unspecified, heading will be taken from the field ``verbose_name`` if applicable, and the
-attribute string otherwise.
+attribute string otherwise. For our example, ``last_published_at`` will automatically get a heading of ``"Last Published At"``,
+but a simple "Last Published" looks neater. We'll add that by setting ``export_heading_overrides``:
+
+``export_heading_overrides = dict(last_published_at='Last Published', **ReportView.export_heading_overrides)``
 
 .. attribute:: custom_value_preprocess
 
@@ -97,6 +107,46 @@ will take priority over functions specified in ``ReportView.custom_value_preproc
 ``ReportView.custom_value_preprocess`` also does not specify a function), ``force_str`` will be used. To prevent
 preprocessing, set the preprocessing_function to ``None``.
 
+Customising templates
+---------------------
+
+For this example "pages with unpublished changes" report, we'll add an extra column to the listing template, showing the last
+publication date for each page. To do this, we'll extend two templates: ``wagtailadmin/reports/base_report.html``, and 
+``wagtailadmin/reports/listing/_list_report.html``.
+
+.. code-block:: html
+
+    # <project>/templates/reports/unpublished_changes_report.html
+
+    {% extends 'wagtailadmin/reports/base_report.html' %}
+
+    {% block listing %}
+        {% include 'reports/include/_list_unpublished_changes.html' %}
+    {% endblock %}
+
+    {% block no_results %}
+        <p>No pages with unpublished changes.</p>
+    {% endblock %}
+
+
+.. code-block:: html
+
+    # <project>/templates/reports/include/_list_unpublished_changes.html
+
+    {% extends 'wagtailadmin/reports/listing/_list_report.html' %}
+
+    {% block extra_columns %}
+        <th>Last Published</th>
+    {% endblock %}
+
+    {% block extra_page_data%}
+        <td valign="top">
+            {{ page.last_published_at }}
+        </td>
+    {% endblock %}
+
+Finally, we'll set ``UnpublishedChangesReportView.template_name`` to this new template: ``'reports/unpublished_changes_report.html'``.
+
 
 Adding a menu item and admin URL
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -113,14 +163,90 @@ url for the report, you will need to use the ``register_admin_urls`` hook (see :
     from wagtail.admin.menu import MenuItem
     from wagtail.core import hooks
 
-    from .views import CustomReportView
+    from .views import UnpublishedChangesReportView
 
     @hooks.register('register_reports_menu_item')
-    def register_my_custom_report_menu_item():
-        return MenuItem("My Custom Report", reverse('my_custom_report'), classnames='icon icon-' + CustomReportView.header_icon, order=700)
+    def register_unpublished_changes_report_menu_item():
+        return MenuItem("Pages with unpublished changes", reverse('unpublished_changes_report'), classnames='icon icon-' + UnpublishedChangesReportView.header_icon, order=700)
     
     @hooks.register('register_admin_urls')
-    def register_my_custom_report_url():
+    def register_unpublished_changes_report_url():
         return [
-            url(r'^reports/my-custom-report/$', CustomReportView.as_view(), name='my_custom_report'),
-        ]
+            url(r'^reports/unpublished-changes/$', UnpublishedChangesReportView.as_view(), name='unpublished_changes_report'),
+        ]
+
+
+The full code
+~~~~~~~~~~~~~
+
+.. code-block:: python
+
+    # <project>/views.py
+
+    from wagtail.admin.views.reports import ReportView
+    from wagtail.core.models import Page
+
+
+    class UnpublishedChangesReportView(ReportView):
+
+        header_icon = 'doc-empty-inverse'
+        template_name = 'reports/unpublished_changes_report.html'
+        title = "Pages with unpublished changes"
+
+        list_export = ReportView.list_export + ['last_published_at']
+        export_heading_overrides = dict(last_published_at='Last Published', **ReportView.export_heading_overrides)
+        
+        def get_queryset(self):
+            return Page.objects.filter(has_unpublished_changes=True)
+
+.. code-block:: python
+
+    # <project>/wagtail_hooks.py
+
+    from django.conf.urls import url
+
+    from wagtail.admin.menu import MenuItem
+    from wagtail.core import hooks
+
+    from .views import UnpublishedChangesReportView
+
+    @hooks.register('register_reports_menu_item')
+    def register_unpublished_changes_report_menu_item():
+        return MenuItem("Pages with unpublished changes", reverse('unpublished_changes_report'), classnames='icon icon-' + UnpublishedChangesReportView.header_icon, order=700)
+    
+    @hooks.register('register_admin_urls')
+    def register_unpublished_changes_report_url():
+        return [
+            url(r'^reports/unpublished-changes/$', UnpublishedChangesReportView.as_view(), name='unpublished_changes_report'),
+        ]
+
+.. code-block:: html
+
+    # <project>/templates/reports/unpublished_changes_report.html
+
+    {% extends 'wagtailadmin/reports/base_report.html' %}
+
+    {% block listing %}
+        {% include 'reports/include/_list_unpublished_changes.html' %}
+    {% endblock %}
+
+    {% block no_results %}
+        <p>No pages with unpublished changes.</p>
+    {% endblock %}
+
+
+.. code-block:: html
+
+    # <project>/templates/reports/include/_list_unpublished_changes.html
+
+    {% extends 'wagtailadmin/reports/listing/_list_report.html' %}
+
+    {% block extra_columns %}
+        <th>Last Published</th>
+    {% endblock %}
+
+    {% block extra_page_data%}
+        <td valign="top">
+            {{ page.last_published_at }}
+        </td>
+    {% endblock %}