@NotThreadSafe @GwtCompatible public final class SafeHtmlBuilder extends Object
SafeHtml
contract. Supports setting
element name, individual attributes and content.
While this builder disallows some invalid HTML constructs (for example, void elements with content) it does not guarantee well-formed HTML (for example, attribute values are not strictly enforced if they pose no security risk). A large number of runtime failures are possible and it is therefore recommended to thoroughly unit test code using this builder.
Modifier and Type | Class and Description |
---|---|
static class |
SafeHtmlBuilder.DirValue
Values that can be passed to
setDir(DirValue) . |
static class |
SafeHtmlBuilder.TargetValue
Values that can be passed to
setTarget(TargetValue) . |
Constructor and Description |
---|
SafeHtmlBuilder(String elementName)
Creates a builder for the given
elementName , which must consist only of lowercase
letters, digits and - . |
Modifier and Type | Method and Description |
---|---|
SafeHtmlBuilder |
appendContent(Iterable<SafeHtml> htmls)
Appends the given
htmls as this element's content, in the sequence the Iterable
returns them. |
SafeHtmlBuilder |
appendContent(Iterator<SafeHtml> htmls)
Appends the given
htmls as this element's content, in the sequence the Iterator
returns them. |
SafeHtmlBuilder |
appendContent(SafeHtml... htmls)
Appends the given
htmls as this element's content, in sequence. |
SafeHtml |
build() |
SafeHtmlBuilder |
escapeAndAppendContent(String text)
HTML-escapes and appends
text to this element's content. |
SafeHtmlBuilder |
setAlt(String value)
Sets the
alt attribute for this element. |
SafeHtmlBuilder |
setClass(String value)
Sets the
class attribute for this element. |
SafeHtmlBuilder |
setColor(String value)
Sets the
color attribute for this element. |
SafeHtmlBuilder |
setDataAttribute(String name,
String value)
Sets a custom data attribute,
name , to value for this element. |
SafeHtmlBuilder |
setDir(SafeHtmlBuilder.DirValue value)
Sets the
dir attribute for this element. |
SafeHtmlBuilder |
setHref(SafeUrl value)
Sets the
href attribute for any element. |
SafeHtmlBuilder |
setHref(TrustedResourceUrl value)
Sets the
href attribute for this element. |
SafeHtmlBuilder |
setId(String value)
Sets the
id attribute for this element. |
SafeHtmlBuilder |
setIdWithPrefix(String prefix,
String value)
Sets the
id attribute for this element, as the concatenation of a
CompileTimeConstant prefix and a value . |
SafeHtmlBuilder |
setName(String value)
Sets the
name attribute for this element. |
SafeHtmlBuilder |
setPlaceholder(String value)
Sets the
placeholder attribute for this element. |
SafeHtmlBuilder |
setRel(String value)
Sets the
rel attribute for any element. |
SafeHtmlBuilder |
setSrc(SafeUrl value)
Sets the
src attribute. |
SafeHtmlBuilder |
setSrc(TrustedResourceUrl value)
Sets the
src attribute for this element. |
SafeHtmlBuilder |
setStyle(SafeStyle value)
Sets the
style attribute for this element. |
SafeHtmlBuilder |
setTarget(SafeHtmlBuilder.TargetValue value)
Sets the
target attribute for this element. |
SafeHtmlBuilder |
setTitle(String value)
Sets the
title attribute for this element. |
SafeHtmlBuilder |
setType(String value)
Sets the
type attribute for this element, if it's one of button ,
command , input , li , menu , ol , or ul . |
SafeHtmlBuilder |
setValue(String value)
Sets the
value attribute for this element. |
SafeHtmlBuilder |
useSlashOnVoid()
Causes the builder to use a slash on the tag of a void element, emitting
e.g.
|
public SafeHtmlBuilder(@CompileTimeConstant String elementName)
elementName
, which must consist only of lowercase
letters, digits and -
.
If elementName
is not a void element then the string representation of the
builder is <elementName[optional attributes]>[optional content]</elementName>
. If
elementName
is a void element then the string representation is
<elementName[optional attributes]>
. Contents between the element's start and end tag
can be set via, for example, appendContent()
.
embed
, object
, script
, style
, template
are not
supported because their content has special semantics, and they can result the execution of
code not under application control. Some of these have dedicated creation methods.
IllegalArgumentException
- if elementName
contains invalid characters or is not
supportedhttp://whatwg.org/html/syntax.html#void-elements
public SafeHtmlBuilder useSlashOnVoid()
<br/>
instead of the default <br>
. Slashes are required
if rendering XHTML and optional in HTML 5.
This setting has no effect for non-void elements.http://www.w3.org/TR/html5/syntax.html#start-tags
public SafeHtmlBuilder setAlt(String value)
alt
attribute for this element.public SafeHtmlBuilder setClass(String value)
class
attribute for this element.public SafeHtmlBuilder setColor(String value)
color
attribute for this element.public SafeHtmlBuilder setDataAttribute(@CompileTimeConstant String name, String value)
name
, to value
for this element. value
must consist only of letters and -
.name
- including the "data-" prefix, e.g. "data-tooltip"IllegalArgumentException
- if the attribute name isn't validhttp://www.w3.org/TR/html5/dom.html#embedding-custom-non-visible-data-with-the-data-*-attributes
public SafeHtmlBuilder setDir(SafeHtmlBuilder.DirValue value)
dir
attribute for this element.public SafeHtmlBuilder setHref(SafeUrl value)
href
attribute for any element. For <link>
elements, setting
this attribute is allowed only if the rel
attribute doesn't contain the substring
"stylesheet
", in which case a TrustedResourceUrl is required.IllegalArgumentException
- if value
is set unsafely on a link
elementpublic SafeHtmlBuilder setHref(TrustedResourceUrl value)
href
attribute for this element.public SafeHtmlBuilder setId(@CompileTimeConstant String value)
id
attribute for this element.public SafeHtmlBuilder setIdWithPrefix(@CompileTimeConstant String prefix, String value)
id
attribute for this element, as the concatenation of a
CompileTimeConstant
prefix
and a value
.IllegalArgumentException
- if prefix
is an empty stringpublic SafeHtmlBuilder setName(String value)
name
attribute for this element.public SafeHtmlBuilder setPlaceholder(String value)
placeholder
attribute for this element.public SafeHtmlBuilder setSrc(SafeUrl value)
src
attribute. Only valid for img
and input
elements, other
elements require TrustedResourceUrl.IllegalArgumentException
- if builder does not represent an allowed elementpublic SafeHtmlBuilder setSrc(TrustedResourceUrl value)
src
attribute for this element.public SafeHtmlBuilder setStyle(SafeStyle value)
style
attribute for this element.public SafeHtmlBuilder setRel(String value)
rel
attribute for any element. For <link>
elements, setting this
attribute to stylesheet
is allowed only if the href
attribute hasn't been set
with a SafeUrl
(instead of a TrustedResourceUrl
. value
must consist
only of letters and spaces.IllegalArgumentException
- if value
is invalid or is set unsafely on a
link
elementpublic SafeHtmlBuilder setType(String value)
type
attribute for this element, if it's one of button
,
command
, input
, li
, menu
, ol
, or ul
.IllegalArgumentException
- if type cannot be set on this elementpublic SafeHtmlBuilder setValue(String value)
value
attribute for this element.public SafeHtmlBuilder setTarget(SafeHtmlBuilder.TargetValue value)
target
attribute for this element.public SafeHtmlBuilder setTitle(String value)
title
attribute for this element.public SafeHtmlBuilder appendContent(SafeHtml... htmls)
htmls
as this element's content, in sequence.IllegalStateException
- if this builder represents a void elementpublic SafeHtmlBuilder appendContent(Iterable<SafeHtml> htmls)
htmls
as this element's content, in the sequence the Iterable
returns them.IllegalStateException
- if this builder represents a void elementpublic SafeHtmlBuilder appendContent(Iterator<SafeHtml> htmls)
htmls
as this element's content, in the sequence the Iterator
returns them.IllegalStateException
- if this builder represents a void elementpublic SafeHtmlBuilder escapeAndAppendContent(String text)
text
to this element's content.IllegalStateException
- if this builder represents a void elementpublic SafeHtml build()