Package org.xwiki.velocity.tools

Class EscapeTool

  • All Implemented Interfaces:
    Serializable
    public class EscapeTool
extends org.apache.velocity.tools.generic.EscapeTool

    Tool for working with escaping in Velocity templates. It provides methods to escape outputs for Velocity, Java, JavaScript, HTML, XML and SQL.

    Extends the default EscapeTool from velocity-tools since the XML escape performed by it doesn't work inside HTML content, since apos is not a valid HTML entity name, and it always escapes non-ASCII characters, which increases the HTML length considerably, while also making the source unreadable.

    Since:
    2.7RC1
    Version:
    $Id: 60ffb3463f39437d661617b2abae4331e721beee $
    See Also:
    Serialized Form

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static String DEFAULT_KEY
      The name of the standard binding to access this tool in XWiki.

      • Fields inherited from class org.apache.velocity.tools.generic.SafeConfig

        LOCK_CONFIG_KEY, log, LOGGER_NAME_KEY, SAFE_MODE_KEY, USE_CLASS_LOGGER_KEY

    • Constructor Summary

      Constructors 
      Constructor Description
      EscapeTool()
      Change the default key defined in EscapeTool.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      String b​(Object content)
      Encode a text using the B encoding specified in RFC 2047.
      String css​(String identifier)
      Escapes a CSS identifier.
      String json​(Object string)
      Escapes the characters in a String using JSON String rules: escapes with backslash double quotes, back and forward slashes, newlines, the control characters \b, \t and \f, and with \uXXXX any non-ASCII characters.
      String q​(Object content)
      Encode a text using the Q encoding specified in RFC 2047.
      String quotedPrintable​(Object content)
      Encode a text using the Quoted-Printable format, as specified in section 6.7 of RFC 2045.
      String url​(Object string)
      We override the implementation so that we sync it with the encoding strategy we use for generating URLs.
      String url​(Map<String,​?> parametersMap)
      Properly escape a parameter map representing a query string, so that it can be safely used in an URL.
      String xml​(Object content)
      Escapes the XML special characters in a String using numerical XML entities.

      • Methods inherited from class org.apache.velocity.tools.generic.EscapeTool

        configure, dumpString, getB, getBackslash, getD, getDollar, getE, getExclamation, getH, getHash, getKey, getN, getNewline, getQ, getQuote, getS, getSingleQuote, html, java, javascript, propertyKey, propertyValue, setKey, sql, unicode, unurl, velocity

      • Methods inherited from class org.apache.velocity.tools.generic.SafeConfig

        configure, getLog, initLogger, isConfigLocked, isSafeMode, setLockConfig, setSafeMode

    • Field Detail

      • DEFAULT_KEY

        public static final String DEFAULT_KEY
        The name of the standard binding to access this tool in XWiki.
        Since:
        14.1RC1, 13.10.3
        See Also:
        Constant Field Values

    • Constructor Detail

      • EscapeTool

        public EscapeTool()
        Change the default key defined in EscapeTool.

    • Method Detail

      • xml

        public String xml​(Object content)
        Escapes the XML special characters in a String using numerical XML entities. This overrides the base implementation from Velocity, which is over-zealous and escapes any non-ASCII character. Since XWiki works with Unicode-capable encodings (UTF-8), there is no need to escape non-special characters.
        Overrides:
        xml in class org.apache.velocity.tools.generic.EscapeTool
        Parameters:
        content - the text to escape, may be null
        Returns:
        a new escaped String, null if null input

      • json

        public String json​(Object string)
        Escapes the characters in a String using JSON String rules: escapes with backslash double quotes, back and forward slashes, newlines, the control characters \b, \t and \f, and with \uXXXX any non-ASCII characters. Unlike EscapeTool.javascript(Object), it does not escape ' , which is not a special character in JSON, and it would be a syntax error to do so.
        Parameters:
        string - the string to escape, may be null; any non-string object will be converted to a string first, using String.valueOf(obj)
        Returns:
        String with escaped values, null if null input
        Since:
        6.1M1

      • quotedPrintable

        public String quotedPrintable​(Object content)
        Encode a text using the Quoted-Printable format, as specified in section 6.7 of RFC 2045. UTF-8 is used as the character encoding, and no line breaking is performed.
        Parameters:
        content - the text to encode
        Returns:
        the text converted into the Quoted-Printable format

      • q

        public String q​(Object content)
        Encode a text using the Q encoding specified in RFC 2047. UTF-8 is used as the character encoding, and no line breaking is performed. The resulting text is already wrapped with the encoded word markers, starting with =?UTF-8?Q? and ending with ?=.
        Parameters:
        content - the text to encode
        Returns:
        the text converted into an encoded word using the Q encoding

      • b

        public String b​(Object content)
        Encode a text using the B encoding specified in RFC 2047. UTF-8 is used as the character encoding, and no line breaking is performed. The resulting text is already wrapped with the encoded word markers, starting with =?UTF-8?B? and ending with ?=.
        Parameters:
        content - the text to encode
        Returns:
        the text converted into an encoded word using the B encoding

      • url

        public String url​(Map<String,​?> parametersMap)
        Properly escape a parameter map representing a query string, so that it can be safely used in an URL. Parameters can have multiple values in which case the value in the map is either an array or a Collection. If the parameter name is null (the key is null) then the parameter is ignored. null values are serialized as an empty string.
        Parameters:
        parametersMap - Map representing the query string.
        Returns:
        the safe query string representing the passed parameters
        Since:
        5.2M1

      • css

        public String css​(String identifier)
        Escapes a CSS identifier.

        See https://drafts.csswg.org/cssom/#serialize-an-identifier.

        Parameters:
        identifier - the identifier to escape
        Returns:
        the escaped identifier
        Since:
        6.4.7, 7.1.4, 7.4M1

      • url

        public String url​(Object string)
        We override the implementation so that we sync it with the encoding strategy we use for generating URLs. Namely we encode all characters and we encode space as %20 and not as + in the query string.
        Overrides:
        url in class org.apache.velocity.tools.generic.EscapeTool
        Parameters:
        string - the url to encode
        Returns:
        the encoded URL
        Since:
        8.3M1