Closure Tools

Functions and Print Directives

Table of Contents

  1. Functions
  2. Print Directives
  3. Custom Functions and Print Directives

This chapter describes basic functions and print directives. For functions and print directives related to bidirectional text, please see the chapter Bidi Support.

Functions

The table below lists the basic functions supported in Soy expressions.

Function Usage
isFirst($var)

Use this with the foreach command. See more information in the foreach section of the Commands chapter.

isLast($var)

Use this with the foreach command. See more information in the foreach section of the Commands chapter.

index($var)

Use this with the foreach command. See more information in the foreach section of the Commands chapter.

isNonnull(value)

Returns true if the given value is both defined and not the value null.

hasData()

Note: This directive is no longer necessary and will be removed in the future. It's currently a no-op. Please remove all usages of hasData() from your Soy code.

length(list)

The length of a list.

keys(map)

The keys in a map as a list. There is no guarantee on order.

augmentMap(baseMap, additionalMap)

Builds an augmented map. The returned map contains mappings from both the base map and the additional map. If the same key appears in both, then the value from the additional map is visible, while the value from the base map is hidden. The base map is used, but not modified.

quoteKeysIfJs(mapLiteral)

This function is only valid when called on a map literal. It is a no-op in backends other than JavaScript. In JS, it causes the generated JS object literal's keys to be quoted strings instead of non-quoted. This makes no difference except in the case where your Soy-generated JS code will later be processed by Closure Compiler.

Specifically, for JS code generation, we now default to non-quoted keys. So the expression ['xxx': $aaa.bbb, 'yyy': 'boo'] might generate something like {xxx: data.aaa.bbb, yyy: 'boo'} which means you can use the usual dot-access in template code $myMap.xxx if your Soy-generated JS code will later be processed by Closure Compiler. On the other hand, if you want to generate JS code for a map with quoted keys (the old behavior), then write the expression quoteKeysIfJs(['xxx': $aaa.bbb, 'yyy': 'boo']), which might generate something like {'xxx': data.aaa.bbb, 'yyy': 'boo'}. In this case, you would have to use bracket-access in template code $myMap['xxx'] if your Soy-generated JS code will later be processed by Closure Compiler.

round(number)

Round to an integer.

round(number, numDigitsAfterDecimalPoint)

If numDigitsAfterDecimalPoint is positive, round to that number of decimal places; if numDigitsAfterDecimalPoint is negative, round to an integer with that many 0s at the end.

floor(number)

The floor of the number.

ceiling(number)

The ceiling of the number.

min(number, number)

The min of the two numbers.

max(number, number)

The max of the two numbers.

randomInt(rangeArg)

A random integer in the range [0, rangeArg - 1] (where rangeArg must be a positive integer).

strContains(str, subStr)

Checks whether a string contains a particular substring.


Print directives are post-processing on the output of a print command. The table below summarizes the directives that you can use with print.

Directive Usage
|noAutoescape

Note: Instead of using this, consider using sanitized content, which is safer.

This directive turns off autoescaping for one print command. By default, autoescaping causes all print output to be HTML-escaped to reduce the chance of cross-site scripting bugs. Using the |noAutoescape directive, e.g. {$productNameHtml |noAutoescape}, prevents the output from being HTML-escaped. This example also demonstrates the convention that known-to-be-safe HTML data values should have keys whose names end in Html.

|id

Note: This directive is deprecated and will be removed in the future. The current recommendation is not to mark ids with any directives at all (neither |id nor |noAutoescape), and simply let the autoescaping pass run on them, which should be a very fast no-op.

Use this to mark a data reference as an identifier, indicating that autoescaping need not be applied. It should only be used for HTML element ids, CSS class names, or other similar identifiers (note that contextual autoescaping handles some of these cases automatically; see Security for details). Example |id directive usage:

<span id="{$myElementId|id}" class="{$myCssClass|id}">
  {$myVar |noAutoescape}  // note: don't use |id for non-identifiers
</span>
      
|escapeHtml

Use this to manually HTML-escape the output of a print command, e.g. {$userName |escapeHtml}. It's usually only needed in templates that have autoescape set to false.

|escapeUri

Use this to escape the output so that it can be inserted into a URI parameter.

|escapeJsString

Use this to escape the output so that it can be inserted into a JavaScript string.

|truncate:<n>[,false]

Use this to truncate a string to a maximum length n with trailing ellipsis. Add the optional ,false to truncate without an ellipsis. For example, 'Lorem Ipsum' |truncate:8 produces Lorem..., while 'Lorem Ipsum' |truncate:8,false produces Lorem Ip.

|insertWordBreaks:<n>

Use this to insert 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 (note that |insertWordBreaks does not check for natural word break characters other than spaces). The parameter is written after the directive name, separated by a colon, e.g. {$userName |insertWordBreaks:5}.

|changeNewlineToBr

Use this to change newlines (\n, \r, or \r\n) to <br>s.


Custom Functions and Print Directives

You can write plugins in Java for any additional functions or print directives that you need. For details, see section Plugins for Functions or Print Directives in Plugins.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.