Deprecated Features

Overview

This chapter documents deprecated Closure Templates features. In general, they should not be used in new templates, but may occasionally be needed when working with older templates.

Deprecated Autoescape Modes

Contextual Autoescaping

Contextual autoescaping is the evolutionary predecessor to strict autoescaping. It is enabled by setting autoescape="deprecated-contextual" in your template or namespace declarations.

Contextual and strict autoescaping share many features. Both have a notion of output contexts and can handle dynamic values that are SanitizedContent objects. The biggest difference between them is what they produce. Strict templates produce SanitizedContent objects that are safe for the content kind that the template author has explicitly declared. By contrast, contextual templates produce plain text that is safe for the content kind that the compiler has implicitly inferred.

Contextual templates also accept directives that are useless in strict templates, including |noAutoescape. (Part of the reason for introducing strict templates was that widespread use of |noAutoescape and similar directives for large projects made it difficult to reason about the behavior and safety of the templates.)

Strict templates can be called from older contextual templates, but not the other way around (with one exception: strict templates with kind text can call non-strict templates). When a contextual template calls a strict template, the compiler ensures that the content kind of the strict template matches the context in the calling template. If not, then the compiler signals an error.

Noncontextual Autoescaping

Noncontextual autoescaping is weaker than both strict and contextual autoescaping. However, it is the default autoescaping mode for templates that do not have an autoescape attribute. (You can also explicitly set noncontextual autoescaping with autoescape="deprecated-noncontextual".)

Noncontextual autoescaping simply assumes the template output will be inserted into HTML, and escapes accordingly. If the template output is inserted into a different context (for example, a <script> block), the escaping will be incorrect and security vulnerabilities can result.

Deprecated Print Directives

|noAutoescape

This directive turns off contextual autoescaping for one print command. Because contextual autoescaping is deprecated, |noAutoescape is deprecated too. Users of strict autoescaping never need to use this directive (and it is actually forbidden in strict templates).

|escapeHtml, |escapeUri, |escapeJsString

These directives manually escape the output of a print command to be safe for the given context (HTML, URI parameters, and JavaScript strings respectively).

Avoid escaping print commands manually. Instead, use strict autoescaping to declare the content kind of a template, and Closure Templates will automatically escape print commands in that template correctly.

|insertWordBreaks

This print directive inserts word break tags (usually <wbr>) into output that needs to be wrapped, but may not contain enough natural word breaks (such as spaces). It takes one parameter: an integer number of consecutive non-space characters to allow before inserting a word break tag. (|insertWordBreaks does not check for natural word break characters other than spaces.)

Instead of |insertWordBreaks, use the CSS word-wrap: break-word property. It does a better job with less performance impact. Inserting word breaks introduces line breaks in undesirable locations, and requires expensive logic to work across all locales.

Parameter declarations in comments

The {@param} command is used to declare template parameters. But in the past, template parameters were also declared using @param tags inside Javadoc-like comment blocks. For example:

/**
 * Renders a person's first and last name.
 * @param firstName {string} The person's first name.
 * @param lastName {string} The person's last name.
 */
{template .renderName}
  ...
{/template}

This syntax allows template authors to document the type of a parameter, but it is not actually enforced by the compiler: their type is the unknown type (?), regardless of the type in the comment. (By contrast, parameters declared with the {@param} command are strongly-typed. Closure Templates performs both compile-time and run-time checks to ensure that the parameter data is consistent with the declared type.)

Although a template may declare parameters using both {@param} commands and @param tags in comment blocks, a given parameter may only be declared once.