From 4bb7351e8e3a60c6d1cb48be81dc0f56732b1362 Mon Sep 17 00:00:00 2001 From: Ben Darnell Date: Thu, 24 Apr 2025 16:01:37 -0400 Subject: [PATCH] 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. --- docs/guide/templates.rst | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) 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. ````. +`.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 -- 2.47.2