Deprecate insert_editor_css in favor of insert_global_admin_css (wagt…

…ail#10499)

Fixes wagtail#10402

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)

CONTRIBUTORS.rst

@@ -712,6 +712,7 @@ Contributors
 * Christer Jensen
 * Virag Jain
 * Lukas von Allmen
+* Ester Beltrami
 
 Translators
 ===========

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.

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`

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`.

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))
 
 

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, '<script src="/path/to/my/custom.js"></script>')
 
+    def test_deprecated_editor_css_hook(self):
+        def css_hook():
+            return '<link rel="stylesheet" href="/some/custom.css">'
+
+        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, '<link rel="stylesheet" href="/some/custom.css">'
+                )
+
 
 class TestSendMail(TestCase):
     def test_send_email(self):

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 """<link rel="stylesheet" href="/path/to/my/custom.css">"""