html.SafeHtml Extends
A string that is safe to use in HTML context in DOM APIs and HTML documents. A SafeHtml is a string-like object that carries the security type contract that its value as a string will not cause untrusted script execution when evaluated as HTML in a browser. Values of this type are guaranteed to be safe to use in HTML contexts, such as, assignment to the innerHTML DOM property, or interpolation into a HTML template in HTML PC_DATA context, in the sense that the use will not result in a Cross-Site-Scripting vulnerability. Instances of this type must be created via the factory methods ( goog.html.SafeHtml.create, goog.html.SafeHtml.htmlEscape), etc and not by invoking its constructor. The constructor intentionally takes no parameters and the type is immutable; hence only a default instance corresponding to the empty string can be obtained via constructor invocation.

Inheritance

Constructor

goog.html.SafeHtml()

Instance Methods

Public Protected Private
getDirection()
No description.
code »
getTypedStringValue()
Returns this SafeHtml's value a string. IMPORTANT: In code where it is security relevant that an object's type is indeed SafeHtml, use goog.html.SafeHtml.unwrap instead of this method. If in doubt, assume that it's security relevant. In particular, note that goog.html functions which return a goog.html type do not guarantee that the returned instance is of the right type. For example:
var fakeSafeHtml = new String('fake');
fakeSafeHtml.__proto__ = goog.html.SafeHtml.prototype;
var newSafeHtml = goog.html.SafeHtml.htmlEscape(fakeSafeHtml);
// newSafeHtml is just an alias for fakeSafeHtml, it's passed through by
// goog.html.SafeHtml.htmlEscape() as fakeSafeHtml
// instanceof goog.html.SafeHtml.
code »
toString()
Returns a debug string-representation of this value. To obtain the actual string value wrapped in a SafeHtml, use goog.html.SafeHtml.unwrap.
code »

Instance Properties

SAFE_HTML_TYPE_MARKER_GOOG_HTML_SECURITY_PRIVATE_ :
A type marker used to implement additional run-time type checking.
Code »
dir_ :
This SafeHtml's directionality, or null if unknown.
Code »
implementsGoogI18nBidiDirectionalString :
No description.
Code »
implementsGoogStringTypedString :
No description.
Code »
privateDoNotAccessOrElseSafeHtmlWrappedValue_ :
The contained value of this SafeHtml. The field has a purposely ugly name to make (non-compiled) code that attempts to directly access this field stand out.
Code »

Static Methods

goog.html.SafeHtml.concat(var_args) !goog.html.SafeHtml
Creates a new SafeHtml object by concatenating the values.
Arguments:
var_args : ...!goog.html.SafeHtml.TextOrHtml_ |  !Array.<!goog.html.SafeHtml.TextOrHtml_>
Elements of array arguments would be processed recursively.
Returns: !goog.html.SafeHtml  No description.
code »
goog.html.SafeHtml.concatWithDir(dirvar_args) !goog.html.SafeHtml
Creates a new SafeHtml object with known directionality by concatenating the values.
Arguments:
dir : !goog.i18n.bidi.Dir
Directionality.
var_args : ...!goog.html.SafeHtml.TextOrHtml_ |  !Array.<!goog.html.SafeHtml.TextOrHtml_>
Elements of array arguments would be processed recursively.
Returns: !goog.html.SafeHtml  No description.
code »
goog.html.SafeHtml.create(tagNameopt_attributesopt_content) !goog.html.SafeHtml
Creates a SafeHtml content consisting of a tag with optional attributes and optional content. For convenience tag names and attribute names are accepted as regular strings, instead of goog.string.Const. Nevertheless, you should not pass user-controlled values to these parameters. Note that these parameters are syntactically validated at runtime, and invalid values will result in an exception. Example usage: goog.html.SafeHtml.create('br'); goog.html.SafeHtml.create('div', {'class': 'a'}); goog.html.SafeHtml.create('p', {}, 'a'); goog.html.SafeHtml.create('p', {}, goog.html.SafeHtml.create('br')); goog.html.SafeHtml.create('span', { 'style': {'margin': '0'} });
Arguments:
tagName : string
The name of the tag. Only tag names consisting of [a-zA-Z0-9-] are allowed. ,
opt_attributes : !Object.<string, goog.html.SafeHtml.AttributeValue_>>
Mapping from attribute names to their values. Only attribute names consisting of [a-zA-Z0-9-] are allowed. Attributes with a special meaning (e.g. on*) require goog.string.Const value, attributes containing URL require goog.string.Const or goog.html.SafeUrl. The "style" attribute accepts goog.html.SafeStyle or a map which will be passed to goog.html.SafeStyle.create. Value of null or undefined causes the attribute to be omitted. Values are HTML-escaped before usage.
opt_content : !goog.html.SafeHtml.TextOrHtml_ |  !Array.<!goog.html.SafeHtml.TextOrHtml_>>
Content to put inside the tag. This must be empty for void tags like
. Array elements are concatenated.
Returns: !goog.html.SafeHtml  The SafeHtml content with the tag.
code »
goog.html.SafeHtml.createSafeHtmlSecurityPrivateDoNotAccessOrElse_(htmldir) !goog.html.SafeHtml
Utility method to create SafeHtml instances. This function is considered "package private", i.e. calls (using "suppress visibility") from other files within this package are considered acceptable. DO NOT call this function from outside the goog.html package; use appropriate wrappers instead.
Arguments:
html : string
The string to initialize the SafeHtml object with.
dir : ?goog.i18n.bidi.Dir
The directionality of the SafeHtml to be constructed, or null if unknown.
Returns: !goog.html.SafeHtml  The initialized SafeHtml object.
code »
goog.html.SafeHtml.createWithDir(dirtagNameopt_attributesopt_content) !goog.html.SafeHtml
Creates a SafeHtml content with known directionality consisting of a tag with optional attributes and optional content.
Arguments:
dir : !goog.i18n.bidi.Dir
Directionality.
tagName : string
No description.
opt_attributes : !Object.<string, goog.html.SafeHtml.AttributeValue_>>
No description.
opt_content : !goog.html.SafeHtml.TextOrHtml_ |  !Array.<!goog.html.SafeHtml.TextOrHtml_>>
No description.
Returns: !goog.html.SafeHtml  The SafeHtml content with the tag.
code »
goog.html.SafeHtml.from(textOrHtml) !goog.html.SafeHtml
Use goog.html.SafeHtml.htmlEscape. Coerces an arbitrary object into a SafeHtml object. If textOrHtml is already of type goog.html.SafeHtml, the same object is returned. Otherwise, textOrHtml is coerced to string, and HTML-escaped. If textOrHtml is of a type that implements goog.i18n.bidi.DirectionalString, its directionality, if known, is preserved.
Arguments:
textOrHtml : !goog.html.SafeHtml.TextOrHtml_
The text or SafeHtml to coerce.
Returns: !goog.html.SafeHtml  The resulting SafeHtml object.
code »
goog.html.SafeHtml.getStyleValue_(value) string
Gets value allowed in "style" attribute.
Arguments:
value : goog.html.SafeHtml.AttributeValue_
It could be SafeStyle or a map which will be passed to goog.html.SafeStyle.create.
Returns: string  Unwrapped value.
code »
goog.html.SafeHtml.htmlEscape(textOrHtml) !goog.html.SafeHtml
Returns HTML-escaped text as a SafeHtml object. If text is of a type that implements goog.i18n.bidi.DirectionalString, the directionality of the new SafeHtml object is set to text's directionality, if known. Otherwise, the directionality of the resulting SafeHtml is unknown (i.e., null).
Arguments:
textOrHtml : !goog.html.SafeHtml.TextOrHtml_
The text to escape. If the parameter is of type SafeHtml it is returned directly (no escaping is done).
Returns: !goog.html.SafeHtml  The escaped text, wrapped as a SafeHtml.
code »
goog.html.SafeHtml.htmlEscapePreservingNewlines(textOrHtml) !goog.html.SafeHtml
Returns HTML-escaped text as a SafeHtml object, with newlines changed to <br>.
Arguments:
textOrHtml : !goog.html.SafeHtml.TextOrHtml_
The text to escape. If the parameter is of type SafeHtml it is returned directly (no escaping is done).
Returns: !goog.html.SafeHtml  The escaped text, wrapped as a SafeHtml.
code »
goog.html.SafeHtml.unwrap(safeHtml) string
Performs a runtime check that the provided object is indeed a SafeHtml object, and returns its value.
Arguments:
safeHtml : !goog.html.SafeHtml
The object to extract from.
Returns: string  The SafeHtml object's contained string, unless the run-time type check fails. In that case, unwrap returns an innocuous string, or, if assertions are enabled, throws goog.asserts.AssertionError.
code »

Static Properties

goog.html.SafeHtml.AttributeValue_ :
No description.
Code »
goog.html.SafeHtml.EMPTY : goog.html.SafeHtml
A SafeHtml instance corresponding to the empty string.
Code »
goog.html.SafeHtml.NOT_ALLOWED_TAG_NAMES_ :
Set of tag names that are too dangerous.
Code »
goog.html.SafeHtml.TYPE_MARKER_GOOG_HTML_SECURITY_PRIVATE_ :
Type marker for the SafeHtml type, used to implement additional run-time type checking.
Code »
goog.html.SafeHtml.TextOrHtml_ :
Shorthand for union of types that can sensibly be converted to strings or might already be SafeHtml (as SafeHtml is a goog.string.TypedString).
Code »
goog.html.SafeHtml.URL_ATTRIBUTES_ :
Set of attributes containing URL as defined at http://www.w3.org/TR/html5/index.html#attributes-1.
Code »
goog.html.SafeHtml.VALID_NAMES_IN_TAG_ :
No description.
Code »

Package html

Package Reference