Deprecate passing JS templates to render_modal_workflow

docs/releases/2.2.rst

@@ -38,3 +38,13 @@ Bug fixes
 
 Upgrade considerations
 ======================
+
+JavaScript templates in modal workflows are deprecated
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``wagtail.admin.modal_workflow`` module (used internally by Wagtail to handle modal popup interfaces such as the page chooser) has been updated to avoid returning JavaScript code as part of HTTP responses. User code that relies on this functionality can be updated as follows:
+
+ * Eliminate template tags from the .js template. Any dynamic data needed by the template can instead be passed in a dict to ``render_modal_workflow``, as a keyword argument ``json_data``; this data will then be available as the second parameter of the JavaScript function.
+ * At the point where you call the ``ModalWorkflow`` constructor, add an ``onload`` option - a dictionary of functions to be called on loading each step of the workflow. Move the code from the .js template into this dictionary. Then, on the call to ``render_modal_workflow``, rather than passing the .js template name (which should now be replaced by ``None``), pass a ``step`` item in the ``json_data`` dictionary to indicate the ``onload`` function to be called.
+
+Additionally, if your code calls ``loadResponseText`` as part of a jQuery AJAX callback, this should now be passed all three arguments from the callback (the response data, status string and XMLHttpRequest object).

wagtail/admin/modal_workflow.py

@@ -1,8 +1,11 @@
 import json
+import warnings
 
 from django.http import HttpResponse, JsonResponse
 from django.template.loader import render_to_string
 
+from wagtail.utils.deprecation import RemovedInWagtail24Warning
+
 
 def render_modal_workflow(request, html_template, js_template, template_vars=None, json_data=None):
     """"
@@ -10,6 +13,11 @@ def render_modal_workflow(request, html_template, js_template, template_vars=Non
     in the format required by the modal-workflow framework.
     """
     if js_template:
+        warnings.warn(
+            "Passing a JS template to render_modal_workflow is deprecated. "
+            "Use an 'onload' dict on the ModalWorkflow constructor instead",
+            category=RemovedInWagtail24Warning
+        )
         # construct response as Javascript, including a JS function as the 'onload' field
         response_keyvars = []
 

wagtail/admin/static_src/wagtailadmin/js/modal-workflow.js

@@ -55,6 +55,8 @@ function ModalWorkflow(opts) {
     };
 
     self.loadResponseText = function(responseText, textStatus, xhr) {
+        /* RemovedInWagtail24Warning - support for eval()-ing text/javascript responses
+        (rather than JSON.parse) will be dropped */
         var response;
         if (xhr && xhr.getResponseHeader('content-type') != 'text/javascript') {
             response = JSON.parse(responseText);