/*
* Copyright 2011 Google Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not
* use this file except in compliance with the License. You may obtain a copy of
* the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations under
* the License.
*/
package com.google.gwt.safecss.shared;
import com.google.gwt.dom.client.Style.BorderStyle;
import com.google.gwt.dom.client.Style.Cursor;
import com.google.gwt.dom.client.Style.Display;
import com.google.gwt.dom.client.Style.Float;
import com.google.gwt.dom.client.Style.FontStyle;
import com.google.gwt.dom.client.Style.FontWeight;
import com.google.gwt.dom.client.Style.ListStyleType;
import com.google.gwt.dom.client.Style.Overflow;
import com.google.gwt.dom.client.Style.Position;
import com.google.gwt.dom.client.Style.TableLayout;
import com.google.gwt.dom.client.Style.TextDecoration;
import com.google.gwt.dom.client.Style.Unit;
import com.google.gwt.dom.client.Style.VerticalAlign;
import com.google.gwt.dom.client.Style.Visibility;
import com.google.gwt.safehtml.shared.SafeUri;
/**
* A builder that facilitates the building up of XSS-safe CSS attribute strings
* from {@link SafeStyles}. It is used essentially like a {@link StringBuilder},
* but access {@link SafeStyles} instead of Strings.
*
* <p>
* The accumulated XSS-safe {@link SafeStyles} can be obtained in the form of a
* {@link SafeStyles} via the {@link #toSafeStyles()} method.
*
* <p>
* This class is not thread-safe.
*/
public final class SafeStylesBuilder {
private final StringBuilder sb = new StringBuilder();
/**
* Constructs an empty {@link SafeStylesBuilder}.
*/
public SafeStylesBuilder() {
}
/**
* Appends the contents of another {@link SafeStyles} object, without applying
* any escaping or sanitization to it.
*
* @param styles the {@link SafeStyles} to append
* @return a reference to this object
*/
public SafeStylesBuilder append(SafeStyles styles) {
sb.append(styles.asString());
return this;
}
/**
* <p>
* Appends {@link 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
* {@link SafeStyles} contract.
*
* <p>
* Generally, {@link SafeStyles} should be of the form
* {@code cssPropertyName:value;}, where neither the name nor the value
* contain malicious scripts.
*
* <p>
* {@link SafeStyles} may never contain literal angle brackets. Otherwise, it
* could be unsafe to place a {@link SafeStyles} into a <style> tag
* (where it can't be HTML escaped). For example, if the {@link SafeStyles}
* containing "
* <code>font: 'foo <style><script>evil</script></code>'" is
* used in a style sheet in a <style> tag, this could then break out of
* the style context into HTML.
*
* <p>
* The following example values comply with this type's contract:
* <ul>
* <li><code>width: 1em;</code></li>
* <li><code>height:1em;</code></li>
* <li><code>width: 1em;height: 1em;</code></li>
* <li><code>background:url('http://url');</code></li>
* </ul>
* In addition, the empty string is safe for use in a CSS attribute.
*
* <p>
* The following example values do <em>not</em> comply with this type's
* contract:
* <ul>
* <li><code>background: red</code> (missing a trailing semi-colon)</li>
* <li><code>background:</code> (missing a value and a trailing semi-colon)</li>
* <li><code>1em</code> (missing an attribute name, which provides context for
* the value)</li>
* </ul>
*
* @param styles the input String
* @return a {@link SafeStyles} instance
*/
public SafeStylesBuilder appendTrustedString(String styles) {
SafeStylesUtils.verifySafeStylesConstraints(styles);
sb.append(styles);
return this;
}
/**
* Append the background-image CSS property.
*
* @param uri the URI of the background image
* @see #trustedBackgroundImage(String)
*/
public SafeStylesBuilder backgroundImage(SafeUri uri) {
return append(SafeStylesUtils.forBackgroundImage(uri));
}
/**
* Append the border-style CSS property.
*/
public SafeStylesBuilder borderStyle(BorderStyle value) {
return append(SafeStylesUtils.forBorderStyle(value));
}
/**
* Append the border-width css property.
*/
public SafeStylesBuilder borderWidth(double value, Unit unit) {
return append(SafeStylesUtils.forBorderWidth(value, unit));
}
/**
* Append the bottom css property.
*/
public SafeStylesBuilder bottom(double value, Unit unit) {
return append(SafeStylesUtils.forBottom(value, unit));
}
/**
* Append the cursor CSS property.
*/
public SafeStylesBuilder cursor(Cursor value) {
return append(SafeStylesUtils.forCursor(value));
}
/**
* Append the display CSS property.
*/
public SafeStylesBuilder display(Display value) {
return append(SafeStylesUtils.forDisplay(value));
}
/**
* Append the float css property.
*
* <p>
* 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.
* </p>
*/
public SafeStylesBuilder floatprop(Float value) {
return append(SafeStylesUtils.forFloat(value));
}
/**
* Append the font-size css property.
*/
public SafeStylesBuilder fontSize(double value, Unit unit) {
return append(SafeStylesUtils.forFontSize(value, unit));
}
/**
* Append the font-style CSS property.
*/
public SafeStylesBuilder fontStyle(FontStyle value) {
return append(SafeStylesUtils.forFontStyle(value));
}
/**
* Append the font-weight CSS property.
*/
public SafeStylesBuilder fontWeight(FontWeight value) {
return append(SafeStylesUtils.forFontWeight(value));
}
/**
* Append the height css property.
*/
public SafeStylesBuilder height(double value, Unit unit) {
return append(SafeStylesUtils.forHeight(value, unit));
}
/**
* Append the left css property.
*/
public SafeStylesBuilder left(double value, Unit unit) {
return append(SafeStylesUtils.forLeft(value, unit));
}
/**
* Append the list-style-type CSS property.
*/
public SafeStylesBuilder listStyleType(ListStyleType value) {
return append(SafeStylesUtils.forListStyleType(value));
}
/**
* Append the margin css property.
*/
public SafeStylesBuilder margin(double value, Unit unit) {
return append(SafeStylesUtils.forMargin(value, unit));
}
/**
* Append the margin-bottom css property.
*/
public SafeStylesBuilder marginBottom(double value, Unit unit) {
return append(SafeStylesUtils.forMarginBottom(value, unit));
}
/**
* Append the margin-left css property.
*/
public SafeStylesBuilder marginLeft(double value, Unit unit) {
return append(SafeStylesUtils.forMarginLeft(value, unit));
}
/**
* Append the margin-right css property.
*/
public SafeStylesBuilder marginRight(double value, Unit unit) {
return append(SafeStylesUtils.forMarginRight(value, unit));
}
/**
* Append the margin-top css property.
*/
public SafeStylesBuilder marginTop(double value, Unit unit) {
return append(SafeStylesUtils.forMarginTop(value, unit));
}
/**
* Append the opacity css property.
*/
public SafeStylesBuilder opacity(double value) {
return append(SafeStylesUtils.forOpacity(value));
}
/**
* Append the overflow CSS property.
*/
public SafeStylesBuilder overflow(Overflow value) {
return append(SafeStylesUtils.forOverflow(value));
}
/**
* Append the overflow-x CSS property.
*/
public SafeStylesBuilder overflowX(Overflow value) {
return append(SafeStylesUtils.forOverflowX(value));
}
/**
* Append the overflow-y CSS property.
*/
public SafeStylesBuilder overflowY(Overflow value) {
return append(SafeStylesUtils.forOverflowY(value));
}
/**
* Append the padding css property.
*/
public SafeStylesBuilder padding(double value, Unit unit) {
return append(SafeStylesUtils.forPadding(value, unit));
}
/**
* Append the padding-bottom css property.
*/
public SafeStylesBuilder paddingBottom(double value, Unit unit) {
return append(SafeStylesUtils.forPaddingBottom(value, unit));
}
/**
* Append the padding-left css property.
*/
public SafeStylesBuilder paddingLeft(double value, Unit unit) {
return append(SafeStylesUtils.forPaddingLeft(value, unit));
}
/**
* Append the padding-right css property.
*/
public SafeStylesBuilder paddingRight(double value, Unit unit) {
return append(SafeStylesUtils.forPaddingRight(value, unit));
}
/**
* Append the padding-top css property.
*/
public SafeStylesBuilder paddingTop(double value, Unit unit) {
return append(SafeStylesUtils.forPaddingTop(value, unit));
}
/**
* Append the position CSS property.
*/
public SafeStylesBuilder position(Position value) {
return append(SafeStylesUtils.forPosition(value));
}
/**
* Append the right css property.
*/
public SafeStylesBuilder right(double value, Unit unit) {
return append(SafeStylesUtils.forRight(value, unit));
}
/**
* Append the table-layout CSS property.
*/
public SafeStylesBuilder tableLayout(TableLayout value) {
return append(SafeStylesUtils.forTableLayout(value));
}
/**
* Append the text-decoration CSS property.
*/
public SafeStylesBuilder textDecoration(TextDecoration value) {
return append(SafeStylesUtils.forTextDecoration(value));
}
/**
* Append the top css property.
*/
public SafeStylesBuilder top(double value, Unit unit) {
return append(SafeStylesUtils.forTop(value, unit));
}
/**
* Returns the safe CSS properties accumulated in the builder as a
* {@link SafeStyles}.
*
* @return a {@link SafeStyles} instance
*/
public SafeStyles toSafeStyles() {
return new SafeStylesString(sb.toString());
}
/**
* <p>
* 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 {@link SafeStyles} contract when they
* are composed into the form: "<name>:<value>;".
*
* <p>
* {@link SafeStyles} may never contain literal angle brackets. Otherwise, it
* could be unsafe to place a {@link SafeStyles} into a <style> tag
* (where it can't be HTML escaped). For example, if the {@link SafeStyles}
* containing "
* <code>font: 'foo <style><script>evil</script></code>'" is
* used in a style sheet in a <style> tag, this could then break out of
* the style context into HTML.
*
* @param value the property value
* @return a {@link SafeStyles} instance
*/
public SafeStylesBuilder trustedBackgroundColor(String value) {
return append(SafeStylesUtils.forTrustedBackgroundColor(value));
}
/**
* <p>
* 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 {@link SafeStyles} contract when they
* are composed into the form: "<name>:<value>;".
*
* <p>
* {@link SafeStyles} may never contain literal angle brackets. Otherwise, it
* could be unsafe to place a {@link SafeStyles} into a <style> tag
* (where it can't be HTML escaped). For example, if the {@link SafeStyles}
* containing "
* <code>font: 'foo <style><script>evil</script></code>'" is
* used in a style sheet in a <style> tag, this could then break out of
* the style context into HTML.
*
* @param value the property value
* @return a {@link SafeStyles} instance
* @see #backgroundImage(SafeUri)
*/
public SafeStylesBuilder trustedBackgroundImage(String value) {
return append(SafeStylesUtils.forTrustedBackgroundImage(value));
}
/**
* <p>
* 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 {@link SafeStyles} contract when they
* are composed into the form: "<name>:<value>;".
*
* <p>
* {@link SafeStyles} may never contain literal angle brackets. Otherwise, it
* could be unsafe to place a {@link SafeStyles} into a <style> tag
* (where it can't be HTML escaped). For example, if the {@link SafeStyles}
* containing "
* <code>font: 'foo <style><script>evil</script></code>'" is
* used in a style sheet in a <style> tag, this could then break out of
* the style context into HTML.
*
* @param value the property value
* @return a {@link SafeStyles} instance
*/
public SafeStylesBuilder trustedBorderColor(String value) {
return append(SafeStylesUtils.forTrustedBorderColor(value));
}
/**
* <p>
* 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 {@link SafeStyles} contract when they are
* composed into the form: "<name>:<value>;".
*
* <p>
* {@link SafeStyles} may never contain literal angle brackets. Otherwise, it
* could be unsafe to place a {@link SafeStyles} into a <style> tag
* (where it can't be HTML escaped). For example, if the {@link SafeStyles}
* containing "
* <code>font: 'foo <style><script>evil</script></code>'" is
* used in a style sheet in a <style> tag, this could then break out of
* the style context into HTML.
*
* @param value the property value
* @return a {@link SafeStyles} instance
*/
public SafeStylesBuilder trustedColor(String value) {
return append(SafeStylesUtils.forTrustedColor(value));
}
/**
* <p>
* Append a {@link 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 {@link SafeStyles} contract when they are composed into the
* form: "<name>:<value>;".
*
* <p>
* {@link SafeStyles} may never contain literal angle brackets. Otherwise, it
* could be unsafe to place a {@link SafeStyles} into a <style> tag
* (where it can't be HTML escaped). For example, if the {@link SafeStyles}
* containing "
* <code>font: 'foo <style><script>evil</script></code>'" is
* used in a style sheet in a <style> tag, this could then break out of
* the style context into HTML.
* </p>
*
* <p>
* The name should be in hyphenated format, not camelCase format.
* </p>
*
* @param name the property name
* @param value the property value
* @return a {@link SafeStyles} instance
*/
public SafeStylesBuilder trustedNameAndValue(String name, double value, Unit unit) {
return append(SafeStylesUtils.fromTrustedNameAndValue(name, value, unit));
}
/**
* <p>
* Append a {@link 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 {@link SafeStyles} contract when they are composed into the
* form: "<name>:<value>;".
*
* <p>
* {@link SafeStyles} may never contain literal angle brackets. Otherwise, it
* could be unsafe to place a {@link SafeStyles} into a <style> tag
* (where it can't be HTML escaped). For example, if the {@link SafeStyles}
* containing "
* <code>font: 'foo <style><script>evil</script></code>'" is
* used in a style sheet in a <style> tag, this could then break out of
* the style context into HTML.
* </p>
*
* <p>
* The name should be in hyphenated format, not camelCase format.
* </p>
*
* @param name the property name
* @param value the property value
* @return a {@link SafeStyles} instance
*/
public SafeStylesBuilder trustedNameAndValue(String name, String value) {
return append(SafeStylesUtils.fromTrustedNameAndValue(name, value));
}
/**
* Append the vertical-align CSS property.
*/
public SafeStylesBuilder verticalAlign(double value, Unit unit) {
return append(SafeStylesUtils.forVerticalAlign(value, unit));
}
/**
* Append the vertical-align CSS property.
*/
public SafeStylesBuilder verticalAlign(VerticalAlign value) {
return append(SafeStylesUtils.forVerticalAlign(value));
}
/**
* Append the visibility CSS property.
*/
public SafeStylesBuilder visibility(Visibility value) {
return append(SafeStylesUtils.forVisibility(value));
}
/**
* Append the width css property.
*/
public SafeStylesBuilder width(double value, Unit unit) {
return append(SafeStylesUtils.forWidth(value, unit));
}
/**
* Append the z-index css property.
*/
public SafeStylesBuilder zIndex(int value) {
return append(SafeStylesUtils.forZIndex(value));
}
}