Add upgrade considerations for migrating non-page reports to universal listings

docs/releases/6.2.md

@@ -186,7 +186,13 @@ and register the results-only view:
 
 #### Adjust the templates
 
-If you are only extending the templates to add your own markup for the listing table, you need to change the `template_name` into `results_template_name` on the view class.
+If you are only extending the templates to add your own markup for the listing table (and not other parts of the view template), you need to change the `template_name` into `results_template_name` on the view class.
+
+For a page report, the following changes are needed:
+
+- Change `template_name` to `results_template_name`, and optionally rename the template (e.g. `reports/unpublished_changes_report.html` to `reports/unpublished_changes_report_results.html`).
+- The template should extend from `wagtailadmin/reports/base_page_report_results.html`.
+- The `listing` and `no_results` blocks should be renamed to `results` and `no_results_message`, respectively.
 
 ```diff
  class UnpublishedChangesReportView(PageReportView):
@@ -194,11 +200,6 @@ If you are only extending the templates to add your own markup for the listing t
 +    results_template_name = "reports/unpublished_changes_report_results.html"
 ```
 
-After renaming the template (e.g. `reports/unpublished_changes_report.html` to `reports/unpublished_changes_report_results.html`), you will need to make a few changes to the template's contents:
-
-- The template should extend from `wagtailadmin/reports/base_page_report_results.html`.
-- The `listing` and `no_results` blocks should be renamed to `results` and `no_results_message`, respectively.
-
 ```diff
  {# <project>/templates/reports/unpublished_changes_report_results.html #}
 
@@ -215,6 +216,59 @@ After renaming the template (e.g. `reports/unpublished_changes_report.html` to `
  {% endblock %}
 ```
 
+For a non-page report, the following changes are needed:
+
+- Change `template_name` to `results_template_name`, and optionally rename the template (e.g. `reports/custom_non_page_report.html` to `reports/custom_non_page_report_results.html`).
+- The template should extend from `wagtailadmin/reports/base_report_results.html`.
+- Existing templates will typically define a `results` block containing both the results listing and the "no results" message; these should now become separate blocks named `results` and `no_results_message`.
+
+**Before:**
+
+```py
+class CustomNonPageReportView(ReportView):
+    template_name = "reports/custom_non_page_report.html"
+```
+
+```html+django
+{# <project>/templates/reports/custom_non_page_report.html #}
+{% extends "wagtailadmin/reports/base_report.html" %}
+
+{% block results %}
+    {% if object_list %}
+        <table class="listing">
+            <!-- Table markup goes here -->
+        </table>
+    {% else %}
+        <p>No results found.</p>
+    {% endif %}
+{% endblock %}
+```
+
+**After:**
+
+```py
+class CustomNonPageReportView(ReportView):
+    results_template_name = "reports/custom_non_page_report_results.html"
+```
+
+```html+django
+{# <project>/templates/reports/custom_non_page_report_results.html #}
+{% extends "wagtailadmin/reports/base_report_results.html" %}
+
+{% block results %}
+    <table class="listing">
+        <!-- Table markup goes here -->
+    </table>
+{% endblock %}
+
+{% block no_results_message %}
+    <p>No results found.</p>
+{% endblock %}
+```
+
+
 If you need to completely customize the view's template, you can still override the `template_name` attribute on the view class. Note that both `ReportView` and `PageReportView` now use the `wagtailadmin/reports/base_report.html` template, which now extends the `wagtailadmin/generic/listing.html` template. The `wagtailadmin/reports/base_page_report.html` template is now unused and should be replaced with `wagtailadmin/reports/base_report.html`.
 
+If you override `template_name`, it is still necessary to set `results_template_name` to a template that extends `wagtailadmin/reports/base_report_results.html` (or `wagtailadmin/reports/base_page_report_results.html` for page reports), so the view can correctly update the listing and show the active filters as you apply or remove any filters.
+
 ## Upgrade considerations - changes to undocumented internals