Add changelog & upgrade considerations for removal of window.chooserUrls

- Fixes #11586
- Fixes #11421
- Fixes #10377

CHANGELOG.txt

@@ -12,6 +12,7 @@ Changelog
  * Add system checks to ensure that `WAGTAIL_DATE_FORMAT`, `WAGTAIL_DATETIME_FORMAT`, `WAGTAIL_TIME_FORMAT` are correctly configured (Rohit Sharma, Coen van der Kamp)
  * Allow custom permissions with the same prefix as built-in permissions (Sage Abdullah)
  * Allow displaying permissions linked to the Admin model's content type (Sage Abdullah)
+ * Add support for Draftail's JavaScript to use chooserUrls provided by entity options & for the Draftail widget to encode lazy URLs/ translations (Elhussein Almasri)
  * Fix: Fix typo in `__str__` for MySQL search index (Jake Howard)
  * Fix: Ensure that unit tests correctly check for migrations in all core Wagtail apps (Matt Westcott)
  * Fix: Correctly handle `date` objects on `human_readable_date` template tag (Jhonatan Lopes)
@@ -32,6 +33,7 @@ Changelog
  * Maintenance: Optimize queries in dashboard panels (Sage Abdullah)
  * Maintenance: Optimize queries in group create/edit view (Sage Abdullah)
  * Maintenance: Move modal-workflow.js script usage to base admin template instead of ad-hoc imports (Elhussein Almasri)
+ * Maintenance: Update all Draftail chooserUrls to be passed in via the Entity options instead of using `window.chooserUrls` globals, removing the need for inline scripts (Elhussein Almasri)
 
 
 6.0.1 (15.02.2024)

docs/extending/extending_draftail.md

@@ -122,6 +122,8 @@ Optionally, we can also define styles for the blocks with the `Draftail-block--h
 
 That’s it! The extra complexity is that you may need to write CSS to style the blocks in the editor.
 
+(creating_new_draftail_editor_entities)=
+
 ### Creating new entities
 
 ```{warning}

docs/releases/6.1.md

@@ -21,6 +21,7 @@ depth: 1
  * Add system checks to ensure that `WAGTAIL_DATE_FORMAT`, `WAGTAIL_DATETIME_FORMAT`, `WAGTAIL_TIME_FORMAT` are [correctly configured](wagtail_date_time_formats) (Rohit Sharma, Coen van der Kamp)
  * Allow custom permissions with the same prefix as built-in permissions (Sage Abdullah)
  * Allow displaying permissions linked to the Admin model's content type (Sage Abdullah)
+ * Add support for Draftail's JavaScript to use chooserUrls provided by entity options & for the Draftail widget to encode lazy URLs/ translations (Elhussein Almasri)
 
 
 ### Bug fixes
@@ -53,6 +54,95 @@ depth: 1
  * Optimize queries in dashboard panels (Sage Abdullah)
  * Optimize queries in group create/edit view (Sage Abdullah)
  * Move modal-workflow.js script usage to base admin template instead of ad-hoc imports (Elhussein Almasri)
+ * Update all Draftail chooserUrls to be passed in via the Entity options instead of using `window.chooserUrls` globals, removing the need for inline scripts (Elhussein Almasri)
 
 
 ## Upgrade considerations
+
+## Upgrade considerations - changes to undocumented internals
+
+### Deprecation of `window.chooserUrls` within Draftail choosers
+
+The undocumented usage of the JavaScript `window.chooserUrls` within Draftail choosers will be removed in a future release.
+
+The following `chooserUrl` object values will be impacted.
+
+-   `anchorLinkChooser`
+-   `documentChooser`
+-   `emailLinkChooser`
+-   `embedsChooser`
+-   `externalLinkChooser`
+-   `imageChooser`
+-   `pageChooser`
+
+Overriding these inner values on the global `window.chooserUrls` object will still override their usage in the Draftail choosers for now but this capability will be removed in a future release.
+
+#### Example
+
+It's recommended that usage of this global is removed in any customisations or third party packages and instead a custom Draftail Entity be used instead. See example below.
+
+##### Old
+
+```python
+# .../wagtail_hooks.py
+
+@hooks.register("insert_editor_js")
+def editor_js():
+    return format_html(
+        """
+        <script>
+            window.chooserUrls.myCustomChooser = '{0}';
+        </script>
+        """,
+        reverse("myapp_chooser:choose"),
+    )
+```
+
+##### New
+
+Remove the `insert_editor_js` hook usage and instead pass the data needed via the Entity's data.
+
+```python
+# .../wagtail_hooks.py
+
+from django.urls import reverse_lazy
+
+@hooks.register("register_rich_text_features")
+def register_my_custom_feature(features):
+    # features.register_link_type...
+
+    features.register_editor_plugin(
+        "draftail",
+        "custom-link",
+        draftail_features.EntityFeature(
+            {
+                "type": "CUSTOM_ITEM",
+                "icon": "doc-full-inverse",
+                "description": gettext_lazy("Item"),
+                "chooserUrls": {
+                    # Important: `reverse_lazy` must be used unless the URL path is hard-coded
+                    "myChooser": reverse_lazy("myapp_chooser:choose")
+                },
+            },
+            js=["..."],
+        ),
+    )
+
+```
+
+#### Overriding existing `chooserUrls` values
+
+To override existing chooser Entities' `chooserUrls` values, here is an example of an unsupported monkey patch can achieve a similar goal.
+
+However, it's recommended that a [custom Entity be created](creating_new_draftail_editor_entities) to be registered as a replacement feature for Draftail customisations as per the documentation.
+
+```py
+# .../wagtail_hooks.py
+from django.urls import reverse_lazy
+
+from wagtail import hooks
+
+@hooks.register("register_rich_text_features")
+def override_embed_feature_url(features):
+    features.plugins_by_editor["draftail"]["embed"].data["chooserUrls"]["embedsChooser"] = reverse_lazy("my_embeds:chooser")
+```