Deprecate `window.wagtailConfig.BULK_ACTION_ITEM_TYPE` usage in JS

- Avoid using a window global and inline scripts to declare the current bulk action's item time
- Deprecate the usage of `window.wagtailConfig.BULK_ACTION_ITEM_TYPE` with a release note and code comment so that it can be removed in a future release
- Update bulk actions footer template to accept a `item_type` arg, adding this to the DOM element for access within the JavaScript
- Allow a fallback on the model name for core models (e.g. page)
- Also ensure that `{{ block.super }}` is consistently added at the top of the `{% block extra_js %}` (as it is with most usage)
- Relates to #9771 and supports a future migration for bulk actions towards Stimulus
- Relates to ongoing work for CSP compliance #1288

CHANGELOG.txt

@@ -57,6 +57,7 @@ Changelog
  * Maintenance: Move `wagtailConfig` values from inline scripts to the `wagtail_config` template tag (LB (Ben) Johnston, Sage Abdullah)
  * Maintenance: Deprecate the `{% locales %}` and `{% js_translation_strings %}` template tags (LB (Ben) Johnston, Sage Abdullah)
  * Maintenance: Ensure multi-line comments are cleaned from custom icons in addition to just single line comments (Jake Howard)
+ * Maintenance: Deprecate `window.wagtailConfig.BULK_ACTION_ITEM_TYPE` usage in JavaScript to reduce reliance on inline scripts (LB (Ben) Johnston)
 
 
 6.2.2 (24.09.2024)

client/src/includes/bulk-actions.js

@@ -11,16 +11,26 @@ const BULK_ACTION_NUM_OBJECTS = '[data-bulk-action-num-objects]';
 const BULK_ACTION_NUM_OBJECTS_IN_LISTING =
   '[data-bulk-action-num-objects-in-listing]';
 
+/**
+ * Get the bulk action item type from the DOM element, allowing the deprecated global to override until
+ * this is fully removed in a future release.
+ * This is used to determine the strings to display in the bulk action footer.
+ * @type {string}
+ */
+const BULK_ACTION_ITEM_TYPE =
+  /** @deprecated RemovedInWagtail70 - Use `data-bulk-action-footer="..."` instead of window.wagtailConfig.* */
+  (wagtailConfig || {}).BULK_ACTION_ITEM_TYPE ||
+  document
+    .querySelector(BULK_ACTION_FOOTER)
+    .getAttribute('data-bulk-action-footer');
 let checkedState = {};
 
 /**
  * Utility function to get the appropriate string for display in action bar
  */
 function getStringForListing(key) {
-  if (wagtailConfig.STRINGS.BULK_ACTIONS[wagtailConfig.BULK_ACTION_ITEM_TYPE]) {
-    return wagtailConfig.STRINGS.BULK_ACTIONS[
-      wagtailConfig.BULK_ACTION_ITEM_TYPE
-    ][key];
+  if (wagtailConfig.STRINGS.BULK_ACTIONS[BULK_ACTION_ITEM_TYPE]) {
+    return wagtailConfig.STRINGS.BULK_ACTIONS[BULK_ACTION_ITEM_TYPE][key];
   }
   return wagtailConfig.STRINGS.BULK_ACTIONS.ITEM[key];
 }

client/src/includes/bulk-actions.test.js

@@ -1,5 +1,3 @@
-import { addBulkActionListeners } from './bulk-actions';
-
 const getHtml = ({ objectIds = [1, 45, 23, 'uuid-1', 'uuid-2'] } = {}) => `
 <main>
   <input data-bulk-action-select-all-checkbox type="checkbox" id="header-select-all"/>
@@ -11,7 +9,7 @@ const getHtml = ({ objectIds = [1, 45, 23, 'uuid-1', 'uuid-2'] } = {}) => `
     )
     .join('')}
   </div>
-  <footer class="footer bulk-actions-choices hidden" data-bulk-action-footer>
+  <footer class="footer bulk-actions-choices hidden" data-bulk-action-footer="PAGE">
     <input data-bulk-action-select-all-checkbox type="checkbox" id="footer-select-all"/>
     <span data-bulk-action-num-objects class="num-objects"></span>
   </footer>
@@ -21,10 +19,9 @@ const getHtml = ({ objectIds = [1, 45, 23, 'uuid-1', 'uuid-2'] } = {}) => `
 describe('bulk-actions', () => {
   beforeAll(() => {
     window.wagtailConfig = {
-      BULK_ACTION_ITEM_TYPE: 'page',
       STRINGS: {
         BULK_ACTIONS: {
-          page: {
+          PAGE: {
             ALL_IN_LISTING: 'ALL_IN_LISTING',
             ALL: 'ALL',
             PLURAL: 'PLURAL',
@@ -44,6 +41,9 @@ describe('bulk-actions', () => {
   beforeEach(() => {
     document.body.innerHTML = getHtml();
 
+    // import after globals (strings) are created
+    const { addBulkActionListeners } = require('./bulk-actions');
+
     // connect listeners
     addBulkActionListeners();
 

docs/releases/6.3.md

@@ -83,6 +83,7 @@ This release adds formal support for Django 5.1.
  * Deprecate the `{% locales %}` and `{% js_translation_strings %}` template tags (LB (Ben) Johnston, Sage Abdullah)
  * Adopt the modern best practice for `beforeunload` usage in `UnsavedController` to trigger a leave page warning when edits have been made (Shubham Mukati, Sage Abdullah)
  * Ensure multi-line comments are cleaned from custom icons in addition to just single line comments (Jake Howard)
+ * Deprecate `window.wagtailConfig.BULK_ACTION_ITEM_TYPE` usage in JavaScript to reduce reliance on inline scripts (LB (Ben) Johnston)
 
 
 ## Upgrade considerations - changes affecting all projects
@@ -103,6 +104,35 @@ To disable the automatic preview update feature, set [`WAGTAIL_AUTO_UPDATE_PREVI
 
 ## Upgrade considerations - changes to undocumented internals
 
+### Deprecation of `window.wagtailConfig.BULK_ACTION_ITEM_TYPE`
+
+As part of migrating away from inline scripts, the undocumented use of `window.wagtailConfig.BULK_ACTION_ITEM_TYPE` as a global has been deprecated and will be removed in a future release.
+
+**Old**
+
+```html+django
+{% block extra_js %}
+    {{ block.super }}
+    <script>
+        window.wagtailConfig.BULK_ACTION_ITEM_TYPE = 'SOME_ITEM';
+    </script>
+{% endblock %}
+```
+
+**New**
+
+Update usage of the `wagtailadmin/bulk_actions/footer.html` template include to declare the `item_type`.
+
+```html+django
+{% block bulk_actions %}
+    {% include 'wagtailadmin/bulk_actions/footer.html' ... item_type="SOME_ITEM" %}
+{% endblock %}
+```
+
+```{note}
+Custom item types for bulk actions are not officially supported yet and this approach is likely to get further changes in the future.
+```
+
 ### Deprecation of the `{% locales %}` template tag
 
 The undocumented `locales` template tag will be removed in a future release.

wagtail/admin/templates/wagtailadmin/bulk_actions/footer.html

@@ -1,5 +1,5 @@
 {% load i18n wagtailadmin_tags %}
-<section class="footer bulk-actions-choices hidden" data-bulk-action-footer aria-labelledby="bulk-actions-heading">
+<section class="footer bulk-actions-choices hidden" data-bulk-action-footer="{% if item_type %}{{ item_type }}{% else %}{{ model_name|upper }}{% endif %}" aria-labelledby="bulk-actions-heading">
     <h2 id="bulk-actions-heading" class="w-sr-only">{% trans "Bulk actions" %}</h2>
     <div class="footer__container">
         {% include 'wagtailadmin/bulk_actions/select_all_checkbox_input.html' with parent=parent %}

wagtail/admin/templates/wagtailadmin/pages/listing.html

@@ -19,9 +19,6 @@
     that column will have the drag and drop buttons to enable ordering
     {% endcomment %}
     {% if not show_ordering_column %}
-        <script>
-            window.wagtailConfig.BULK_ACTION_ITEM_TYPE = 'PAGE';
-        </script>
         <script defer src="{% versioned_static 'wagtailadmin/js/bulk-actions.js' %}"></script>
     {% endif %}
 {% endblock %}

wagtail/documents/templates/wagtaildocs/documents/index.html

@@ -3,13 +3,10 @@
 
 {% block extra_js %}
     {{ block.super }}
-    <script>
-        window.wagtailConfig.BULK_ACTION_ITEM_TYPE = 'DOCUMENT';
-    </script>
     <script defer src="{% versioned_static 'wagtailadmin/js/bulk-actions.js' %}"></script>
 {% endblock %}
 
 {% block bulk_actions %}
     {% trans "Select all documents in listing" as select_all_text %}
-    {% include 'wagtailadmin/bulk_actions/footer.html' with select_all_obj_text=select_all_text app_label=model_opts.app_label model_name=model_opts.model_name objects=page_obj parent=current_collection.id %}
+    {% include 'wagtailadmin/bulk_actions/footer.html' with select_all_obj_text=select_all_text app_label=model_opts.app_label model_name=model_opts.model_name objects=page_obj parent=current_collection.id item_type="DOCUMENT" %}
 {% endblock %}

wagtail/images/templates/wagtailimages/images/index.html

@@ -3,9 +3,6 @@
 
 {% block extra_js %}
     {{ block.super }}
-    <script>
-        window.wagtailConfig.BULK_ACTION_ITEM_TYPE = 'IMAGE';
-    </script>
     <script defer src="{% versioned_static 'wagtailadmin/js/bulk-actions.js' %}"></script>
 {% endblock %}
 
@@ -24,5 +21,5 @@
 
 {% block bulk_actions %}
     {% trans "Select all images in listing" as select_all_text %}
-    {% include 'wagtailadmin/bulk_actions/footer.html' with select_all_obj_text=select_all_text app_label=model_opts.app_label model_name=model_opts.model_name objects=page_obj parent=current_collection.id %}
+    {% include 'wagtailadmin/bulk_actions/footer.html' with select_all_obj_text=select_all_text app_label=model_opts.app_label model_name=model_opts.model_name objects=page_obj parent=current_collection.id item_type="IMAGE" %}
 {% endblock %}

wagtail/snippets/templates/wagtailsnippets/snippets/index.html

@@ -2,14 +2,11 @@
 {% load i18n wagtailadmin_tags %}
 
 {% block extra_js %}
-    <script>
-        window.wagtailConfig.BULK_ACTION_ITEM_TYPE = 'SNIPPET';
-    </script>
-    <script defer src="{% versioned_static 'wagtailadmin/js/bulk-actions.js' %}"></script>
     {{ block.super }}
+    <script defer src="{% versioned_static 'wagtailadmin/js/bulk-actions.js' %}"></script>
 {% endblock %}
 
 {% block bulk_actions %}
     {% trans "Select all snippets in listing" as select_all_text %}
-    {% include 'wagtailadmin/bulk_actions/footer.html' with select_all_obj_text=select_all_text app_label=model_opts.app_label model_name=model_opts.model_name objects=page_obj %}
+    {% include 'wagtailadmin/bulk_actions/footer.html' with select_all_obj_text=select_all_text app_label=model_opts.app_label model_name=model_opts.model_name objects=page_obj item_type="SNIPPET" %}
 {% endblock %}

wagtail/users/templates/wagtailusers/users/index.html

@@ -2,13 +2,10 @@
 {% load i18n wagtailadmin_tags %}
 {% block extra_js %}
     {{ block.super }}
-    <script>
-        window.wagtailConfig.BULK_ACTION_ITEM_TYPE = 'USER';
-    </script>
     <script defer src="{% versioned_static 'wagtailadmin/js/bulk-actions.js' %}"></script>
 {% endblock %}
 
 {% block bulk_actions %}
     {% trans "Select all users in listing" as select_all_text %}
-    {% include 'wagtailadmin/bulk_actions/footer.html' with select_all_obj_text=select_all_text app_label=model_opts.app_label model_name=model_opts.model_name objects=page_obj %}
+    {% include 'wagtailadmin/bulk_actions/footer.html' with select_all_obj_text=select_all_text app_label=model_opts.app_label model_name=model_opts.model_name objects=page_obj item_type="USER" %}
 {% endblock %}