From c5f238f98d5d23ed9f4eb4162128d7de3f2dbc8c Mon Sep 17 00:00:00 2001 From: Etty Date: Thu, 1 Jun 2023 13:41:24 +0100 Subject: [PATCH] Deprecate insert_editor_css in favor of insert_global_admin_css (#10499) Fixes #10402 --- CHANGELOG.txt | 1 + CONTRIBUTORS.rst | 1 + .../customisation/streamfield_blocks.md | 2 +- docs/reference/hooks.md | 6 ++++++ docs/releases/5.1.md | 5 ++++- wagtail/admin/templatetags/wagtailadmin_tags.py | 9 ++++++++- wagtail/admin/tests/tests.py | 16 ++++++++++++++++ wagtail/test/testapp/wagtail_hooks.py | 2 +- 8 files changed, 38 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.txt b/CHANGELOG.txt index ad0f539b8a54..0e1623b9cb17 100644 --- a/CHANGELOG.txt +++ b/CHANGELOG.txt @@ -18,6 +18,7 @@ Changelog * Docs: Update documentation for `log_action` parameter on `RevisionMixin.save_revision` (Christer Jensen) * Docs: Reorganise snippets documentation to cover customisations and optional features (Sage Abdullah) * Maintenance: Switch to ruff for flake8 / isort code checking (Oliver Parker) + * Maintenance: Deprecate `insert_editor_css` in favour of `insert_global_admin_css` (Ester Beltrami) 5.0.1 (25.05.2023) diff --git a/CONTRIBUTORS.rst b/CONTRIBUTORS.rst index 0d60b2df1e35..2f1c4d2491b5 100644 --- a/CONTRIBUTORS.rst +++ b/CONTRIBUTORS.rst @@ -712,6 +712,7 @@ Contributors * Christer Jensen * Virag Jain * Lukas von Allmen +* Ester Beltrami Translators =========== diff --git a/docs/advanced_topics/customisation/streamfield_blocks.md b/docs/advanced_topics/customisation/streamfield_blocks.md index a79b3609f41b..1da66bb923c6 100644 --- a/docs/advanced_topics/customisation/streamfield_blocks.md +++ b/docs/advanced_topics/customisation/streamfield_blocks.md @@ -20,7 +20,7 @@ class PersonBlock(blocks.StructBlock): form_classname = 'person-block struct-block' ``` -You can then provide custom CSS for this block, targeted at the specified classname, by using the [](insert_editor_css) hook. +You can then provide custom CSS for this block, targeted at the specified classname, by using the [](insert_global_admin_css) hook. ```{note} Wagtail's editor styling has some built in styling for the `struct-block` class and other related elements. If you specify a value for `form_classname`, it will overwrite the classes that are already applied to `StructBlock`, so you must remember to specify the `struct-block` as well. diff --git a/docs/reference/hooks.md b/docs/reference/hooks.md index fa6f6d810360..5c713c5ba9a1 100644 --- a/docs/reference/hooks.md +++ b/docs/reference/hooks.md @@ -454,6 +454,12 @@ def editor_css(): ) ``` +```{note} +The `insert_editor_css` hook is deprecated and will be removed in a future release. We recommend using [](insert_global_admin_css) instead. +``` + + + (insert_global_admin_css)= ### `insert_global_admin_css` diff --git a/docs/releases/5.1.md b/docs/releases/5.1.md index ca8a22b0e6c5..f5a20a968379 100644 --- a/docs/releases/5.1.md +++ b/docs/releases/5.1.md @@ -39,8 +39,11 @@ FieldPanels can now be marked as read-only with the `read_only=True` keyword arg ### Maintenance * Switch to ruff for flake8 / isort code checking (Oliver Parker) + * Deprecate `insert_editor_css` in favour of `insert_global_admin_css` (Ester Beltrami) ## Upgrade considerations -### ... +### `insert_editor_css` hook is deprecated + +The `insert_editor_css` hook has been deprecated. The `insert_global_admin_css` hook has the same functionality, and all uses of `insert_editor_css` should be changed to `insert_global_admin_css`. diff --git a/wagtail/admin/templatetags/wagtailadmin_tags.py b/wagtail/admin/templatetags/wagtailadmin_tags.py index b0fa6a02964c..3f86aa60f8b8 100644 --- a/wagtail/admin/templatetags/wagtailadmin_tags.py +++ b/wagtail/admin/templatetags/wagtailadmin_tags.py @@ -276,12 +276,19 @@ def test_page_is_public(context, page): @register.simple_tag def hook_output(hook_name): """ - Example: {% hook_output 'insert_editor_css' %} + Example: {% hook_output 'insert_global_admin_css' %} Whenever we have a hook whose functions take no parameters and return a string, this tag can be used to output the concatenation of all of those return values onto the page. Note that the output is not escaped - it is the hook function's responsibility to escape unsafe content. """ snippets = [fn() for fn in hooks.get_hooks(hook_name)] + + if hook_name == "insert_editor_css" and snippets: + warn( + "The `insert_editor_css` hook is deprecated - use `insert_global_admin_css` instead.", + category=RemovedInWagtail60Warning, + ) + return mark_safe("".join(snippets)) diff --git a/wagtail/admin/tests/tests.py b/wagtail/admin/tests/tests.py index 9b8ae38d51e5..239fec0bf13a 100644 --- a/wagtail/admin/tests/tests.py +++ b/wagtail/admin/tests/tests.py @@ -13,12 +13,14 @@ from django.utils.translation import gettext_lazy as _ from taggit.models import Tag +from wagtail import hooks from wagtail.admin.auth import user_has_any_page_permission from wagtail.admin.mail import send_mail from wagtail.admin.menu import MenuItem from wagtail.models import Page from wagtail.test.testapp.models import RestaurantTag from wagtail.test.utils import WagtailTestUtils +from wagtail.utils.deprecation import RemovedInWagtail60Warning class TestHome(WagtailTestUtils, TestCase): @@ -157,6 +159,20 @@ def test_editor_js_hooks_on_edit(self): self.assertEqual(response.status_code, 200) self.assertContains(response, '') + def test_deprecated_editor_css_hook(self): + def css_hook(): + return '' + + with self.assertWarnsMessage( + RemovedInWagtail60Warning, + "The `insert_editor_css` hook is deprecated - use `insert_global_admin_css` instead.", + ): + with hooks.register_temporarily("insert_editor_css", css_hook): + response = self.client.get(reverse("wagtailadmin_home")) + self.assertContains( + response, '' + ) + class TestSendMail(TestCase): def test_send_email(self): diff --git a/wagtail/test/testapp/wagtail_hooks.py b/wagtail/test/testapp/wagtail_hooks.py index eee6ad1ae0ca..95a831abf3c3 100644 --- a/wagtail/test/testapp/wagtail_hooks.py +++ b/wagtail/test/testapp/wagtail_hooks.py @@ -34,7 +34,7 @@ # Register one hook using decorators... -@hooks.register("insert_editor_css") +@hooks.register("insert_global_admin_css") def editor_css(): return """"""