Class SafeHtmlUtils
-
Field Summary
-
Method Summary
Modifier and TypeMethodDescriptionstatic SafeHtml
Returns aSafeHtml
constructed from a safe string, i.e., without escaping the string.static SafeHtml
fromString
(String s) Returns aSafeHtml
containing the escaped string.static SafeHtml
Returns aSafeHtml
constructed from a trusted string, i.e., without escaping the string.static String
htmlEscape
(char c) HTML-escapes a character.static String
htmlEscape
(String s) HTML-escapes a string.static String
HTML-escapes a string, but does not double-escape HTML-entities already present in the string.
-
Field Details
-
EMPTY_SAFE_HTML
An empty String.
-
-
Method Details
-
fromSafeConstant
Returns aSafeHtml
constructed from a safe string, i.e., without escaping the string.Important: For this method to be able to honor the
SafeHtml
contract, all uses of this method must satisfy the following constraints:- The argument expression must be fully determined at compile time.
- The value of the argument must end in "inner HTML" context and not
contain incomplete HTML tags. I.e., the following is not a correct use of
this method, because the
<a>
tag is incomplete:shb.appendHtmlConstant("<a href='").append(url)
The first constraint provides a sufficient condition that the argument (and any HTML markup contained in it) originates from a trusted source. The second constraint ensures the composability of
SafeHtml
values.When executing client-side in Development Mode, or server-side with assertions enabled, the argument is HTML-parsed and validated to satisfy the second constraint (the server-side check can also be enabled programmatically, see
SafeHtmlHostedModeUtils.maybeCheckCompleteHtml(String)
for details). For performance reasons, this check is not performed in Production Mode on the client, and with assertions disabled on the server.- Parameters:
s
- the string to be wrapped as aSafeHtml
- Returns:
s
, wrapped as aSafeHtml
- Throws:
IllegalArgumentException
- if not running in Production Mode andhtml
violates the second constraint
-
fromString
Returns aSafeHtml
containing the escaped string.- Parameters:
s
- the input String- Returns:
- a
SafeHtml
instance
-
fromTrustedString
Returns aSafeHtml
constructed from a trusted string, i.e., without escaping the string. No checks are performed. The calling code should be carefully reviewed to ensure the argument meets theSafeHtml
contract.- Parameters:
s
- the input String- Returns:
- a
SafeHtml
instance
-
htmlEscape
HTML-escapes a character. HTML meta characters will be escaped as follows:& - & < - < > - > " - " ' - '
- Parameters:
c
- the character to be escaped- Returns:
- a string containing either the input character or an equivalent HTML Entity Reference
-
htmlEscape
HTML-escapes a string.Note: The following variants of this function were profiled on FF40, Chrome44, Safari 8 and IE11:
- For each metachar, check indexOf, then use s.replace(regex, string)
- For each metachar use s.replace(regex, string)
- Manual replace each metachar by looping through characters in a loop.
- Check if any metachar is present using a regex, then use #1.
- Check if any metachar is present using a regex, then use #2.
- Check if any metachar is present using a regex, then use #3.
For all browsers #4 was found to be the fastest, and is used below.
The only out-lier was firefox with #6 being the optimal option, but #6 performs considerably worse in all other browsers.
- Parameters:
s
- the string to be escaped- Returns:
- the input string, with all occurrences of HTML meta-characters replaced with their corresponding HTML Entity References
-
htmlEscapeAllowEntities
HTML-escapes a string, but does not double-escape HTML-entities already present in the string.- Parameters:
text
- the string to be escaped- Returns:
- the input string, with all occurrences of HTML meta-characters replaced with their corresponding HTML Entity References, with the exception that ampersand characters are not double-escaped if they form the start of an HTML Entity Reference
-