Package com.google.gwt.safecss.shared

Class SafeStylesBuilder

java.lang.Object
com.google.gwt.safecss.shared.SafeStylesBuilder
public final class SafeStylesBuilder extends 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.

  • Constructor Details

    • SafeStylesBuilder

      public SafeStylesBuilder()
      Constructs an empty SafeStylesBuilder.

  • Method Details

    • 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(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

    • backgroundImage

      public SafeStylesBuilder backgroundImage(SafeUri uri)
      Append the background-image CSS property.
      Parameters:
      uri - the URI of the background image
      See Also:

    • borderStyle

      public SafeStylesBuilder borderStyle(Style.BorderStyle value)
      Append the border-style CSS property.

    • borderWidth

      public SafeStylesBuilder borderWidth(double value, Style.Unit unit)
      Append the border-width css property.

    • bottom

      public SafeStylesBuilder bottom(double value, Style.Unit unit)
      Append the bottom css property.

    • clear

      public SafeStylesBuilder clear(Style.Clear value)
      Append the 'clear' CSS property.

    • cursor

      public SafeStylesBuilder cursor(Style.Cursor value)
      Append the cursor CSS property.

    • display

      public SafeStylesBuilder display(Style.Display value)
      Append the display CSS property.

    • floatprop

      public SafeStylesBuilder floatprop(Style.Float value)
      Append the float css property.

      Note: This method has the suffix "prop" to avoid Java compilation errors. The term "float" is a reserved word in Java representing the primitive float.

    • fontSize

      public SafeStylesBuilder fontSize(double value, Style.Unit unit)
      Append the font-size css property.

    • fontStyle

      public SafeStylesBuilder fontStyle(Style.FontStyle value)
      Append the font-style CSS property.

    • fontWeight

      public SafeStylesBuilder fontWeight(Style.FontWeight value)
      Append the font-weight CSS property.

    • height

      public SafeStylesBuilder height(double value, Style.Unit unit)
      Append the height css property.

    • left

      public SafeStylesBuilder left(double value, Style.Unit unit)
      Append the left css property.

    • listStyleType

      public SafeStylesBuilder listStyleType(Style.ListStyleType value)
      Append the list-style-type CSS property.

    • margin

      public SafeStylesBuilder margin(double value, Style.Unit unit)
      Append the margin css property.

    • marginBottom

      public SafeStylesBuilder marginBottom(double value, Style.Unit unit)
      Append the margin-bottom css property.

    • marginLeft

      public SafeStylesBuilder marginLeft(double value, Style.Unit unit)
      Append the margin-left css property.

    • marginRight

      public SafeStylesBuilder marginRight(double value, Style.Unit unit)
      Append the margin-right css property.

    • marginTop

      public SafeStylesBuilder marginTop(double value, Style.Unit unit)
      Append the margin-top css property.

    • opacity

      public SafeStylesBuilder opacity(double value)
      Append the opacity css property.

    • overflow

      public SafeStylesBuilder overflow(Style.Overflow value)
      Append the overflow CSS property.

    • overflowX

      public SafeStylesBuilder overflowX(Style.Overflow value)
      Append the overflow-x CSS property.

    • overflowY

      public SafeStylesBuilder overflowY(Style.Overflow value)
      Append the overflow-y CSS property.

    • padding

      public SafeStylesBuilder padding(double value, Style.Unit unit)
      Append the padding css property.

    • paddingBottom

      public SafeStylesBuilder paddingBottom(double value, Style.Unit unit)
      Append the padding-bottom css property.

    • paddingLeft

      public SafeStylesBuilder paddingLeft(double value, Style.Unit unit)
      Append the padding-left css property.

    • paddingRight

      public SafeStylesBuilder paddingRight(double value, Style.Unit unit)
      Append the padding-right css property.

    • paddingTop

      public SafeStylesBuilder paddingTop(double value, Style.Unit unit)
      Append the padding-top css property.

    • position

      public SafeStylesBuilder position(Style.Position value)
      Append the position CSS property.

    • right

      public SafeStylesBuilder right(double value, Style.Unit unit)
      Append the right css property.

    • tableLayout

      public SafeStylesBuilder tableLayout(Style.TableLayout value)
      Append the table-layout CSS property.

    • textAlign

      public SafeStylesBuilder textAlign(Style.TextAlign value)
      Append the 'text-align' CSS property.

    • textDecoration

      public SafeStylesBuilder textDecoration(Style.TextDecoration value)
      Append the text-decoration CSS property.

    • textIndent

      public SafeStylesBuilder textIndent(double value, Style.Unit unit)
      Append the 'text-indent' CSS property.

    • textJustify

      public SafeStylesBuilder textJustify(Style.TextJustify value)
      Append the 'text-justify' CSS3 property.

    • textOverflow

      public SafeStylesBuilder textOverflow(Style.TextOverflow value)
      Append the 'text-overflow' CSS3 property.

    • textTransform

      public SafeStylesBuilder textTransform(Style.TextTransform value)
      Append the 'text-transform' CSS property.

    • top

      public SafeStylesBuilder top(double value, Style.Unit unit)
      Append the top css property.

    • toSafeStyles

      public SafeStyles toSafeStyles()
      Returns the safe CSS properties accumulated in the builder as a SafeStyles.
      Returns:
      a SafeStyles instance

    • trustedBackgroundColor

      public SafeStylesBuilder trustedBackgroundColor(String value)

      Append the trusted background color, i.e., without escaping the value. No checks are performed. The calling code should be carefully reviewed to ensure the argument will satisfy the SafeStyles contract when they are composed into the form: "<name>:<value>;".

      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.

      Parameters:
      value - the property value
      Returns:
      a SafeStyles instance

    • trustedBackgroundImage

      public SafeStylesBuilder trustedBackgroundImage(String value)

      Append the trusted background image, i.e., without escaping the value. No checks are performed. The calling code should be carefully reviewed to ensure the argument will satisfy the SafeStyles contract when they are composed into the form: "<name>:<value>;".

      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.

      Parameters:
      value - the property value
      Returns:
      a SafeStyles instance
      See Also:

    • trustedBorderColor

      public SafeStylesBuilder trustedBorderColor(String value)

      Append the trusted border color, i.e., without escaping the value. No checks are performed. The calling code should be carefully reviewed to ensure the argument will satisfy the SafeStyles contract when they are composed into the form: "<name>:<value>;".

      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.

      Parameters:
      value - the property value
      Returns:
      a SafeStyles instance

    • trustedColor

      public SafeStylesBuilder trustedColor(String value)

      Append the trusted font color, i.e., without escaping the value. No checks are performed. The calling code should be carefully reviewed to ensure the argument will satisfy the SafeStyles contract when they are composed into the form: "<name>:<value>;".

      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.

      Parameters:
      value - the property value
      Returns:
      a SafeStyles instance

    • trustedNameAndValue

      public SafeStylesBuilder trustedNameAndValue(String name, double value, Style.Unit unit)

      Append a SafeStyles constructed from a trusted name and a trusted value, i.e., without escaping the name and value. No checks are performed. The calling code should be carefully reviewed to ensure the argument will satisfy the SafeStyles contract when they are composed into the form: "<name>:<value>;".

      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 name should be in hyphenated format, not camelCase format.

      Parameters:
      name - the property name
      value - the property value
      Returns:
      a SafeStyles instance

    • trustedNameAndValue

      public SafeStylesBuilder trustedNameAndValue(String name, String value)

      Append a SafeStyles constructed from a trusted name and a trusted value, i.e., without escaping the name and value. No checks are performed. The calling code should be carefully reviewed to ensure the argument will satisfy the SafeStyles contract when they are composed into the form: "<name>:<value>;".

      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 name should be in hyphenated format, not camelCase format.

      Parameters:
      name - the property name
      value - the property value
      Returns:
      a SafeStyles instance

    • verticalAlign

      public SafeStylesBuilder verticalAlign(double value, Style.Unit unit)
      Append the vertical-align CSS property.

    • verticalAlign

      public SafeStylesBuilder verticalAlign(Style.VerticalAlign value)
      Append the vertical-align CSS property.

    • visibility

      public SafeStylesBuilder visibility(Style.Visibility value)
      Append the visibility CSS property.

    • whiteSpace

      public SafeStylesBuilder whiteSpace(Style.WhiteSpace whiteSpace)
      Append the 'white-space' CSS property.

    • width

      public SafeStylesBuilder width(double value, Style.Unit unit)
      Append the width css property.

    • zIndex

      public SafeStylesBuilder zIndex(int value)
      Append the z-index css property.