From: Ben Darnell <ben@bendarnell.com>
Date: Thu, 24 Apr 2025 20:01:37 +0000 (-0400)
Subject: docs: Document the need to use json_encode in javascript contexts
X-Git-Tag: v6.5.0b1~9^2
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F3485%2Fhead;p=thirdparty%2Ftornado.git

docs: Document the need to use json_encode in javascript contexts

This has always been necessary but we didn't have any explicit guidance
for using javascript in templates before.
---

diff --git a/docs/guide/templates.rst b/docs/guide/templates.rst
index db2ef453..036aec22 100644
--- a/docs/guide/templates.rst
+++ b/docs/guide/templates.rst
@@ -118,8 +118,25 @@ Consequently, if you write random stuff inside of your template
 expressions, you will get random Python errors when you execute the
 template.
 
-All template output is escaped by default, using the
-`tornado.escape.xhtml_escape` function. This behavior can be changed
+Security
+~~~~~~~~
+
+Inserting untrusted content into a web page can lead to security vulnerabilities such as cross-site
+scripting (XSS). All data that is passed to a template should be *escaped* to prevent these
+vulnerabilities. The correct form of escaping is context-dependent; Tornado's templates are not
+aware of the syntax of HTML, JavaScript, etc, and so the template developer must sometimes
+explicitly apply the correct escaping function.
+
+The default escaping function is `tornado.escape.xhtml_escape`, which is appropriate for HTML body
+content (but not attribute values). In other cases, other functions should be used. In JavaScript,
+use the `.json_encode` function, e.g. ``<script>var x = {{ json_encode(some_object) }};</script>``.
+`.json_encode` can be used to escape strings, numbers, lists, and dicts. In this example, the
+JavaScript variable ``x`` will be the corresponding JavaScript type (string, number, array, or
+object), and not the JSON-encoded string representation. Note that it is unsafe to use
+`.json_encode` in the context of a JavaScript string literal (including template strings), only in
+the top-level syntactic context.
+
+The automatic escaping behavior can be disabled
 globally by passing ``autoescape=None`` to the `.Application` or
 `.tornado.template.Loader` constructors, for a template file with the
 ``{% autoescape None %}`` directive, or for a single expression by