goog.html.SafeUrl.unwrap
, this type's
contract does not guarantee that instances are safe to interpolate into HTML
without appropriate escaping.
Note also that this type's contract does not imply any guarantees regarding
the resource the URL refers to. In particular, SafeUrls are not
safe to use in a context where the referred-to resource is interpreted as
trusted code, e.g., as the src of a script tag.
Instances of this type must be created via the factory methods
( goog.html.SafeUrl.from
, goog.html.SafeUrl.sanitize
), 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.
Utility method to create SafeUrl 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:
Returns: !goog.html.SafeUrl
The initialized SafeUrl object.
|
code » | ||
Creates a SafeUrl object from a compile-time constant string.
Compile-time constant strings are inherently program-controlled and hence
trusted.
Arguments:
|
code » | ||
Normalizes
url the UTF-8 encoding of url, using a whitelist of
characters. Whitelisted characters are not percent-encoded.
|
code » | ||
Creates a SafeUrl object from
url . If url is a
goog.html.SafeUrl then it is simply returned. Otherwise the input string is
validated to match a pattern of commonly used safe URLs. The string is
converted to UTF-8 and non-whitelisted characters are percent-encoded. The
string wrapped by the created SafeUrl will thus contain only ASCII printable
characters.
url may be a URL with the http, https, or mailto scheme,
or a relative URL (i.e., a URL without a scheme; specifically, a
scheme-relative, absolute-path-relative, or path-relative URL).
url is converted to UTF-8 and non-whitelisted characters are
percent-encoded. Whitelisted characters are '%' and, from RFC 3986,
unreserved characters and reserved characters, with the exception of '\'',
'(' and ')'. This ensures the the SafeUrl contains only ASCII-printable
characters and reduces the chance of security bugs were it to be
interpolated into a specific context without the necessary escaping.
If url fails validation or does not UTF-16 decode correctly
(JavaScript strings are UTF-16 encoded), this function returns a SafeUrl
object containing an innocuous string, goog.html.SafeUrl.INNOCUOUS_STRING.
Arguments:
Returns: !goog.html.SafeUrl
The validated URL, wrapped as a SafeUrl.
|
code » | ||
Performs a runtime check that the provided object is indeed a SafeUrl
object, and returns its value.
IMPORTANT: The guarantees of the SafeUrl type contract only extend to the
behavior of browsers when interpreting URLs. Values of SafeUrl objects MUST
be appropriately escaped before embedding in a HTML document. Note that the
required escaping is context-sensitive (e.g. a different escaping is
required for embedding a URL in a style property within a style
attribute, as opposed to embedding in a href attribute).
Note that the returned value does not necessarily correspond to the string
with which the SafeUrl was constructed, since goog.html.SafeUrl.sanitize
will percent-encode many characters.
Arguments:
Returns: string
The SafeUrl 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 » |