com.google.template.soy.data

Class UnsafeSanitizedContentOrdainer

java.lang.Object

com.google.template.soy.data.UnsafeSanitizedContentOrdainer

@ParametersAreNonnullByDefault
public final class UnsafeSanitizedContentOrdainer
extends Object

Restricted class to create SanitizedContent objects.

Creating a SanitizedContent object is potentially dangerous, as it means you're swearing in advance the content won't cause a cross site scripting vulnerability. In the long term it is nearly impossible to show that any piece of code will always produce safe content -- for example, a parameter that is safe one day may be vulnerable after a refactoring that uses it in a different way.

We suggest you limit your usage of this to just a few files in your code base. Create a small set of utility files that generate and sanitize at the same time. Example utilities:

• Serializing JSON objects from a data structure.
• Running a sanitizer on HTML for an email message.
• Extracting a field from a protocol message that is always run-time sanitized by a backend. It's useful to label the protocol message fields with a "SafeHtml" suffix to reinforce.

Method Summary

Modifier and Type	Method and Description
static SanitizedContent	ordainAsSafe(String value, SanitizedContent.ContentKind kind) Faithfully assumes the provided value is "safe" and marks it not to be re-escaped.
static SanitizedContent	ordainAsSafe(String value, SanitizedContent.ContentKind kind, Dir dir) Faithfully assumes the provided value is "safe" and marks it not to be re-escaped.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

ordainAsSafe

public static SanitizedContent ordainAsSafe(String value,
                                            SanitizedContent.ContentKind kind)

Faithfully assumes the provided value is "safe" and marks it not to be re-escaped. The value's direction is assumed to be LTR for JS, URI, ATTRIBUTES, and CSS content, and otherwise unknown.

When you "ordain" a string as safe content, it means that Soy will NOT re-escape or validate the contents if printed in the relevant context. You can use this to insert known-safe HTML into a template via a parameter.

This doesn't do a lot of strict checking, but makes it easier to differentiate safe constants in your code.

ordainAsSafe

public static SanitizedContent ordainAsSafe(String value,
                                            SanitizedContent.ContentKind kind,
                                            @Nullable
                                            Dir dir)

Faithfully assumes the provided value is "safe" and marks it not to be re-escaped. Also assumes the provided direction; null means unknown and thus to be estimated when necessary.

When you "ordain" a string as safe content, it means that Soy will NOT re-escape or validate the contents if printed in the relevant context. You can use this to insert known-safe HTML into a template via a parameter.

This doesn't do a lot of strict checking, but makes it easier to differentiate safe constants in your code.