From e68478777d4a43435cd354f7a6589056e82a4571 Mon Sep 17 00:00:00 2001
From: Matt Westcott <matt@west.co.tt>
Date: Mon, 4 Jun 2018 15:21:57 +0100
Subject: [PATCH] Deprecate passing JS templates to render_modal_workflow

---
 docs/releases/2.2.rst                                  | 10 ++++++++++
 wagtail/admin/modal_workflow.py                        |  8 ++++++++
 .../admin/static_src/wagtailadmin/js/modal-workflow.js |  2 ++
 3 files changed, 20 insertions(+)

diff --git a/docs/releases/2.2.rst b/docs/releases/2.2.rst
index fcef0bf87..e1ec5e6c8 100644
--- a/docs/releases/2.2.rst
+++ b/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).
diff --git a/wagtail/admin/modal_workflow.py b/wagtail/admin/modal_workflow.py
index d2643a8ee..119cc0e61 100644
--- a/wagtail/admin/modal_workflow.py
+++ b/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 = []
 
diff --git a/wagtail/admin/static_src/wagtailadmin/js/modal-workflow.js b/wagtail/admin/static_src/wagtailadmin/js/modal-workflow.js
index 6438e8353..cd988ecaa 100644
--- a/wagtail/admin/static_src/wagtailadmin/js/modal-workflow.js
+++ b/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);