@NotThreadSafe @GwtCompatible public final class SafeStyleBuilder extends Object
SafeStyle
.
The builder allows a sequence of CSS declarations to be constructed by combining trusted
and untrusted values. Trusted values are passed via CompileTimeConstant
strings and
enums. Untrusted values are passed via regular strings and are subject to runtime sanitization
and, if deemed unsafe, replaced by an innocuous value, INNOCUOUS_PROPERTY_STRING
.
This builder does not guarantee semantically valid CSS, only that the generated SafeStyle fulfills its type contract.
This builder currently lacks support for most CSS properties, if you need support for a missing one please contact [email protected].
Constructor and Description |
---|
SafeStyleBuilder() |
Modifier and Type | Method and Description |
---|---|
SafeStyleBuilder |
backgroundAttachmentAppend(String value,
String... otherValues)
Appends
values to the background-attachment property. |
SafeStyleBuilder |
backgroundColor(String value)
Sets
value as the background-color property. |
SafeStyleBuilder |
backgroundColorFromConstant(String constant)
Sets
constant as the background-color property. |
SafeStyleBuilder |
backgroundImageAppendConstant(String constant)
Appends
constant to the background-image property, if necessary inserting a
leading comma. |
SafeStyleBuilder |
backgroundImageAppendUrl(String url)
Appends a
url value to the background-image property, if necessary inserting
a leading comma. |
SafeStyleBuilder |
backgroundPosition(String value)
Sets
value as the background-position property. |
SafeStyleBuilder |
backgroundRepeat(String value)
Sets
value as the background-repeat property |
SafeStyleBuilder |
backgroundSizeAppend(String value,
String... otherValues)
Appends
values to the background-size property. |
SafeStyleBuilder |
border(String value)
Sets
value as the border property. |
SafeStyleBuilder |
borderColor(String value)
Sets
value as the border-color property. |
SafeStyleBuilder |
borderColorFromConstant(String constant)
Sets
constant as the border-color property. |
SafeStyleBuilder |
bottom(String value)
Sets
value as the bottom property. |
SafeStyle |
build() |
SafeStyleBuilder |
display(String value)
Sets
value as the display property. |
SafeStyleBuilder |
fontFamilyAppend(String value,
String... otherValues)
Appends
values to the font-family property. |
SafeStyleBuilder |
height(String value)
Sets
value as the height property. |
SafeStyleBuilder |
left(String value)
Sets
value as the left property. |
SafeStyleBuilder |
lineHeight(String value)
Sets
value as the line-height property. |
SafeStyleBuilder |
margin(String value)
Sets
value as the margin property. |
SafeStyleBuilder |
overflow(String value)
Sets
value as the overflow property. |
SafeStyleBuilder |
overflowX(String value)
Sets
value as the overflow-x property. |
SafeStyleBuilder |
overflowY(String value)
Sets
value as the overflow-y property. |
SafeStyleBuilder |
padding(String value)
Sets
value as the padding property. |
SafeStyleBuilder |
right(String value)
Sets
value as the right property. |
SafeStyleBuilder |
top(String value)
Sets
value as the top property. |
SafeStyleBuilder |
width(String value)
Sets
value as the width property. |
public SafeStyleBuilder backgroundAttachmentAppend(String value, String... otherValues)
values
to the background-attachment
property. Values will be comma
separated.
The values must consist of only ASCII alphabetic or '-' characters. A non-conforming value
will be replaced with INNOCUOUS_PROPERTY_STRING
.
public SafeStyleBuilder backgroundColorFromConstant(@CompileTimeConstant String constant)
constant
as the background-color
property.
Only minimal runtime validation is performed on constant
; being under application
control, it is assumed to be valid and to not break the syntactic structure of the underlying
CSS (by, for example, including comment markers).
IllegalArgumentException
- if constant
contains blacklisted characters or comment
markers: '<', '>', '"', '\'', ';', "//", "/*" or "*/"public SafeStyleBuilder backgroundColor(String value)
value
as the background-color
property.
The value must contain only whitelisted characters; those are alphanumerics, space,
tab, and the set [+-.!#%_/*]
. In addition, comment markers - //
, /*
,
and */
- are disallowed too. Non-conforming values are replaced with
INNOCUOUS_PROPERTY_STRING
.
public SafeStyleBuilder backgroundImageAppendConstant(@CompileTimeConstant String constant)
constant
to the background-image
property, if necessary inserting a
leading comma. Note that constant
itself can contain commas, to separate multiple
values being set on the property. Note that since "//" is not allowed, this method cannot
be used to append URLs, instead use backgroundImageAppendUrl(String)
Only minimal runtime validation is performed on constant
; being under application
control, it is assumed to be valid and to not break the syntactic structure of the underlying
CSS (by, for example, including comment markers).
IllegalArgumentException
- if constant
contains blacklisted characters or comment
markers: '<', '>', '"', '\'', ';', "//", "/*" or "*/"public SafeStyleBuilder backgroundImageAppendUrl(String url)
url
value to the background-image
property, if necessary inserting
a leading comma. The url
value will be inserted inside a url
function call.
The url
is validated as safe, as determined by SafeUrls.sanitize(String)
.
It also percent-encoded to prevent it from interefering with the structure of the surrounding
CSS.
TODO(user): The right thing to do would be to CSS-escape but percent-encoding is easier for now because we don't have a CSS-escaper. As URLs in CSS are likely to point to domains we control it seems extremely unlikely that this will break anything.
public SafeStyleBuilder backgroundSizeAppend(String value, String... otherValues)
values
to the background-size
property. Values will be comma
separated.
All values must contain only whitelisted characters; those are alphanumerics, space,
tab, and the set [+-.!#%_/*]
. In addition, comment markers - //
, /*
,
and */
- are disallowed too. Non-conforming values are replaced with
INNOCUOUS_PROPERTY_STRING
.
public SafeStyleBuilder border(String value)
value
as the border
property.
The value must contain only whitelisted characters; those are alphanumerics, space,
tab, and the set [+-.!#%_/*]
. In addition, comment markers - //
, /*
,
and */
- are disallowed too. Non-conforming values are replaced with
INNOCUOUS_PROPERTY_STRING
.
public SafeStyleBuilder bottom(String value)
value
as the bottom
property.
The value must contain only whitelisted characters; those are alphanumerics, space,
tab, and the set [+-.!#%_/*]
. In addition, comment markers - //
, /*
,
and */
- are disallowed too. Non-conforming values are replaced with
INNOCUOUS_PROPERTY_STRING
.
public SafeStyleBuilder padding(String value)
value
as the padding
property.
The value must contain only whitelisted characters; those are alphanumerics, space,
tab, and the set [+-.!#%_/*]
. In addition, comment markers - //
, /*
,
and */
- are disallowed too. Non-conforming values are replaced with
INNOCUOUS_PROPERTY_STRING
.
public SafeStyleBuilder margin(String value)
value
as the margin
property.
The value must contain only whitelisted characters; those are alphanumerics, space,
tab, and the set [+-.!#%_/*]
. In addition, comment markers - //
, /*
,
and */
- are disallowed too. Non-conforming values are replaced with
INNOCUOUS_PROPERTY_STRING
.
public SafeStyleBuilder display(String value)
value
as the display
property.
The values must consist of only ASCII alphabetic or '-' characters. A non-conforming value
will be replaced with INNOCUOUS_PROPERTY_STRING
.
public SafeStyleBuilder backgroundRepeat(String value)
value
as the background-repeat
property
The value must contain only whitelisted characters; those are alphanumerics, space,
tab, and the set [+-.!#%_/*]
. In addition, comment markers - //
, /*
,
and */
- are disallowed too. Non-conforming values are replaced with
INNOCUOUS_PROPERTY_STRING
.
public SafeStyleBuilder borderColorFromConstant(@CompileTimeConstant String constant)
constant
as the border-color
property.
Only minimal runtime validation is performed on constant
; being under application
control, it is assumed to be valid and to not break the syntactic structure of the underlying
CSS (by, for example, including comment markers).
IllegalArgumentException
- if constant
contains blacklisted characters or comment
markers: '<', '>', '"', '\'', ';', "//", "/*" or "*/"public SafeStyleBuilder borderColor(String value)
value
as the border-color
property.
The value must contain only whitelisted characters; those are alphanumerics, space,
tab, and the set [+-.!#%_/*]
. In addition, comment markers - //
, /*
,
and */
- are disallowed too. Non-conforming values are replaced with
INNOCUOUS_PROPERTY_STRING
.
public SafeStyleBuilder fontFamilyAppend(String value, String... otherValues)
values
to the font-family
property. Values will be comma separated.
If a value consists only of only ASCII alphabetic or '-' characters, it is appended as is,
since it might be a generic font family (like serif
) which must not be quoted. If a
value contains other characters it will be quoted, since quoting might be required (for
example, if the font name contains a space) and unnecessary quoting is allowed.
Values must contain only whitelisted characters; those are alphanumerics, space,
tab, and the set [+-.!#%_/*]
. In addition, comment markers - //
, /*
,
and */
- are disallowed too. Non-conforming values are replaced with
INNOCUOUS_PROPERTY_STRING
.
public SafeStyleBuilder height(String value)
value
as the height
property.
The value must contain only whitelisted characters; those are alphanumerics, space,
tab, and the set [+-.!#%_/*]
. In addition, comment markers - //
, /*
,
and */
- are disallowed too. Non-conforming values are replaced with
INNOCUOUS_PROPERTY_STRING
.
public SafeStyleBuilder backgroundPosition(String value)
value
as the background-position
property.
The value must contain only whitelisted characters; those are alphanumerics, space,
tab, and the set [+-.!#%_/*]
. In addition, comment markers - //
, /*
,
and */
- are disallowed too. Non-conforming values are replaced with
INNOCUOUS_PROPERTY_STRING
.
public SafeStyleBuilder left(String value)
value
as the left
property.
The value must contain only whitelisted characters; those are alphanumerics, space,
tab, and the set [+-.!#%_/*]
. In addition, comment markers - //
, /*
,
and */
- are disallowed too. Non-conforming values are replaced with
INNOCUOUS_PROPERTY_STRING
.
public SafeStyleBuilder lineHeight(String value)
value
as the line-height
property.
The value must contain only whitelisted characters; those are alphanumerics, space,
tab, and the set [+-.!#%_/*]
. In addition, comment markers - //
, /*
,
and */
- are disallowed too. Non-conforming values are replaced with
INNOCUOUS_PROPERTY_STRING
.
public SafeStyleBuilder overflow(String value)
value
as the overflow
property.
The values must consist of only ASCII alphabetic or '-' characters. A non-conforming value
will be replaced with INNOCUOUS_PROPERTY_STRING
.
public SafeStyleBuilder overflowX(String value)
value
as the overflow-x
property.
The values must consist of only ASCII alphabetic or '-' characters. A non-conforming value
will be replaced with INNOCUOUS_PROPERTY_STRING
.
public SafeStyleBuilder overflowY(String value)
value
as the overflow-y
property.
The values must consist of only ASCII alphabetic or '-' characters. A non-conforming value
will be replaced with INNOCUOUS_PROPERTY_STRING
.
public SafeStyleBuilder right(String value)
value
as the right
property.
The value must contain only whitelisted characters; those are alphanumerics, space,
tab, and the set [+-.!#%_/*]
. In addition, comment markers - //
, /*
,
and */
- are disallowed too. Non-conforming values are replaced with
INNOCUOUS_PROPERTY_STRING
.
public SafeStyleBuilder top(String value)
value
as the top
property.
The value must contain only whitelisted characters; those are alphanumerics, space,
tab, and the set [+-.!#%_/*]
. In addition, comment markers - //
, /*
,
and */
- are disallowed too. Non-conforming values are replaced with
INNOCUOUS_PROPERTY_STRING
.
public SafeStyleBuilder width(String value)
value
as the width
property.
The value must contain only whitelisted characters; those are alphanumerics, space,
tab, and the set [+-.!#%_/*]
. In addition, comment markers - //
, /*
,
and */
- are disallowed too. Non-conforming values are replaced with
INNOCUOUS_PROPERTY_STRING
.
public SafeStyle build()