+ {% blocktrans with version=current_version %} + The guide currently covers Wagtail {{ version }}. + {% endblocktrans %} +
+ {% endif %} +| {% trans 'Title' %} | +{% trans 'Status' %} | +{% trans 'Type' %} | +{% trans 'Change type' %} | +{% trans 'Version' %} | +{% trans 'Content' %} | +{% trans 'Review' %} | +
|---|---|---|---|---|---|---|
| + + {{ page.specific_deferred.get_admin_display_title }} + + {% if page.live %} + {% trans 'View' %} + {% endif %} + | ++ {% include "wagtailadmin/shared/page_status_tag.html" with page=page %} + | +{{ page.page_type_display_name }} | +
+
|
+
+
|
+
+
|
+ + {% if page.block_usage_flagged %} + {% trans 'Needs update' %} + {% else %} + {% trans 'Up to date' %} + {% endif %} + | +
{% trans 'No pages with versioned blocks found.' %}
+{% endblock %} \ No newline at end of file diff --git a/apps/core/tests/test_block_usage_report.py b/apps/core/tests/test_block_usage_report.py new file mode 100644 index 00000000..f83d497c --- /dev/null +++ b/apps/core/tests/test_block_usage_report.py @@ -0,0 +1,105 @@ +import json +from http import HTTPStatus + +from django.contrib.auth import get_user_model +from django.test import TestCase +from django.urls import reverse + +from apps.core.factories import ContentPageFactory, HomePageFactory +from apps.core.reports import iter_annotated_blocks + + +def _annotated_body(**kwargs): + value = {"content": kwargs.pop("content", "Some content
")} + value.update(kwargs) + return json.dumps([{"type": "text_annotated", "value": value}]) + + +class TestBlockUsageReport(TestCase): + def setUp(self): + self.home = HomePageFactory() + self.user = get_user_model().objects.create_superuser( + username="admin", password="test" + ) + self.client.login(username="admin", password="test") + self.url = reverse("block_usage_report") + + def test_report_accessible_by_superuser(self): + response = self.client.get(self.url) + self.assertEqual(response.status_code, HTTPStatus.OK) + + def test_report_requires_login(self): + self.client.logout() + response = self.client.get(self.url) + self.assertEqual(response.status_code, HTTPStatus.FOUND) + + def test_pages_without_annotated_blocks_excluded(self): + ContentPageFactory(body=json.dumps([{"type": "text", "value": "Hi
"}])) + response = self.client.get(self.url) + self.assertContains(response, "No pages with versioned blocks found.") + + def test_removed_block_at_outdated_version_flagged(self): + ContentPageFactory(body=_annotated_body(change_type="removed", version="7.0")) + response = self.client.get(self.url) + self.assertContains(response, "Removed") + self.assertContains(response, "7.0") + self.assertContains(response, "Needs update") + + def test_removed_block_at_current_version_not_flagged(self): + ContentPageFactory(body=_annotated_body(change_type="removed", version="7.4")) + response = self.client.get(self.url) + self.assertContains(response, "Removed") + self.assertContains(response, "Up to date") + + def test_outdated_version_flagged(self): + ContentPageFactory(body=_annotated_body(change_type="added", version="5.0")) + response = self.client.get(self.url) + self.assertContains(response, "5.0") + self.assertNotContains(response, "Outdated") + self.assertContains(response, "Needs update") + + def test_current_version_not_outdated(self): + ContentPageFactory(body=_annotated_body(change_type="added", version="7.4")) + response = self.client.get(self.url) + self.assertNotContains(response, "Outdated") + self.assertContains(response, "Up to date") + + def test_flagged_pages_sorted_first(self): + ContentPageFactory( + title="Flagged page", + body=_annotated_body(change_type="added", version="5.0"), + ) + ContentPageFactory( + title="Clean page", + body=json.dumps( + [ + {"type": "text_annotated", "value": {"content": "ok
"}}, + ] + ), + ) + response = self.client.get(self.url) + body = response.content.decode() + self.assertTrue(body.index("Flagged page") < body.index("Clean page")) + + +class TestIterAnnotatedBlocks(TestCase): + def setUp(self): + self.home = HomePageFactory() + + def test_yields_only_annotated_blocks(self): + body = json.dumps( + [ + {"type": "text", "value": "plain
"}, + {"type": "text_annotated", "value": {"content": "a
"}}, + {"type": "text_annotated", "value": {"content": "b
"}}, + ] + ) + page = ContentPageFactory(body=body) + blocks = list(iter_annotated_blocks(page)) + self.assertEqual(len(blocks), 2) + self.assertEqual(blocks[0][0], 1) + self.assertEqual(blocks[1][0], 2) + + def test_empty_when_no_annotated_blocks(self): + body = json.dumps([{"type": "text", "value": "plain
"}]) + self.assertEqual(list(iter_annotated_blocks(ContentPageFactory(body=body))), []) diff --git a/apps/core/wagtail_hooks.py b/apps/core/wagtail_hooks.py index 49801f0c..f1dd24d0 100644 --- a/apps/core/wagtail_hooks.py +++ b/apps/core/wagtail_hooks.py @@ -1,5 +1,7 @@ import wagtail.admin.rich_text.editors.draftail.features as draftail_features -from django.urls import reverse +from django.templatetags.static import static +from django.urls import path, reverse +from django.utils.html import format_html from wagtail import hooks from wagtail.admin.menu import MenuItem from wagtail.admin.rich_text.converters.html_to_contentstate import ( @@ -7,11 +9,13 @@ ) from wagtail.admin.ui.components import Component from wagtail.models import Page +from wagtail.permissions import page_permission_policy from wagtail.snippets.models import register_snippet from wagtail.snippets.views.snippets import SnippetViewSet from wagtail_ai.panels import AIDescriptionFieldPanel from apps.core.models.feedback import Feedback +from apps.core.reports import BlockUsageReportView STYLE_GUIDE_URL = "https://github.com/wagtail/guide/blob/main/docs/style-guide.md" CONTRIBUTING_URL = "https://github.com/wagtail/guide/blob/main/CONTRIBUTING.md" @@ -96,6 +100,49 @@ def register_agent_skills_help_menu_item(): ) +class BlockUsageReportMenuItem(MenuItem): + def is_shown(self, request): + return page_permission_policy.user_has_any_permission( + request.user, ["add", "change", "publish"] + ) + + +@hooks.register("register_reports_menu_item") +def register_block_usage_report_menu_item(): + return BlockUsageReportMenuItem( + "Annotated blocks usage", + reverse("block_usage_report"), + name="block-usage", + icon_name="doc-empty-inverse", + order=1300, + ) + + +@hooks.register("register_admin_urls") +def register_block_usage_report_urls(): + return [ + path( + "reports/block-usage/", + BlockUsageReportView.as_view(), + name="block_usage_report", + ), + path( + "reports/block-usage/results/", + BlockUsageReportView.as_view(results_only=True), + name="block_usage_report_results", + ), + ] + + +@hooks.register("insert_editor_js") +def insert_block_focus_js(): + return format_html( + '\n', + static("core/css/block_usage_focus.css"), + static("core/js/block_usage_focus.js"), + ) + + @hooks.register("register_rich_text_features") def register_inline_code_feature(features): features.default_features.append("code") diff --git a/apps/guide/settings/base.py b/apps/guide/settings/base.py index b6ef5eb1..5c3bba8d 100644 --- a/apps/guide/settings/base.py +++ b/apps/guide/settings/base.py @@ -380,6 +380,10 @@ WAGTAIL_SITE_NAME = "Wagtail user guide 📚️" +# Current Wagtail version covered by the guide, in x.y format (e.g. "7.4"). +# Used by the Block usage report to flag annotated blocks that reference +WAGTAIL_GUIDE_CURRENT_VERSION = "7.4" + # Search # https://docs.wagtail.org/en/stable/topics/search/backends.html WAGTAILSEARCH_BACKENDS = {