com.google.gwt.safecss.shared
Class SafeStylesBuilder

java.lang.Object
  com.google.gwt.safecss.shared.SafeStylesBuilder

public final class SafeStylesBuilder
extends java.lang.Object

A builder that facilitates the building up of XSS-safe CSS attribute strings from SafeStyles. It is used essentially like a StringBuilder, but access SafeStyles instead of Strings.

The accumulated XSS-safe SafeStyles can be obtained in the form of a SafeStyles via the toSafeStyles() method.

This class is not thread-safe.

SafeStylesBuilder

public SafeStylesBuilder()

Constructs an empty SafeStylesBuilder.

append

public SafeStylesBuilder append(SafeStyles styles)

Appends the contents of another SafeStyles object, without applying any escaping or sanitization to it.

Parameters:

styles - the SafeStyles to append

Returns:

a reference to this object

appendTrustedString

public SafeStylesBuilder appendTrustedString(java.lang.String styles)

Appends SafeStyles constructed from a trusted string, i.e., without escaping the string. Only minimal checks are performed. The calling code should be carefully reviewed to ensure the argument meets the SafeStyles contract.

Generally, SafeStyles should be of the form cssPropertyName:value;, where neither the name nor the value contain malicious scripts.

SafeStyles may never contain literal angle brackets. Otherwise, it could be unsafe to place a SafeStyles into a <style> tag (where it can't be HTML escaped). For example, if the SafeStyles containing " font: 'foo <style><script>evil</script>'" is used in a style sheet in a <style> tag, this could then break out of the style context into HTML.

The following example values comply with this type's contract:

• width: 1em;
• height:1em;
• width: 1em;height: 1em;
• background:url('http://url');

In addition, the empty string is safe for use in a CSS attribute.

The following example values do not comply with this type's contract:

• background: red (missing a trailing semi-colon)
• background: (missing a value and a trailing semi-colon)
• 1em (missing an attribute name, which provides context for the value)

Parameters:

styles - the input String

Returns:

a SafeStyles instance

toSafeStyles

public SafeStyles toSafeStyles()

Returns the safe CSS properties accumulated in the builder as a SafeStyles.

Returns:

a SafeStyles instance