The Velocity Project < Velocity Tools - Library >

Velocity Tools

Generic Tools

Tool Documentation

Other Subprojects

EscapeTool Reference Documentation

Tool for working with escaping in Velocity templates.

It provides methods to escape outputs for Java, JavaScript, HTML, XML and SQL. Also provides methods to render VTL characters that otherwise needs escaping.

Class
 org.apache.velocity.tools.generic.EscapeTool
Name
 $esc (this is the recommended name of the tool in the Velocity context)
Toolbox Configuration Example
 
<tool>
  <key>esc</key>
  <scope>application</scope>
  <class>org.apache.velocity.tools.generic.EscapeTool</class>
</tool>
Author(s)
  Shinobu Kawai
Method Overview
java() Escapes the characters in a String using Java String rules.
javascript() Escapes the characters in a String using JavaScript String rules.
html() Escapes the characters in a String using HTML entities.
url() Escapes the characters in a String to be suitable to use as an HTTP parameter value.
xml() Escapes the characters in a String using XML entities.
sql() Escapes the characters in a String to be suitable to pass to an SQL query.
propertyKey() Escapes the characters in a String using the rules for writing Java properties into a properties file.
propertyValue() Escapes the characters in a String using the rules for Java properties.
getDollar() Renders a dollar sign ($).
getD() Renders a dollar sign ($).
getHash() Renders a hash (#).
getH() Renders a hash (#).
getBackslash() Renders a backslash (\).
getB() Renders a backslash (\).
getQuote() Renders a double quotation mark (").
getQ() Renders a double quotation mark (").
getSingleQuote() Renders a single quotation mark (').
getS() Renders a single quotation mark (').
getExclamation() Renders an exclamation mark (!).
getE() Renders an exclamation mark (!).

java()

Escapes the characters in a String using Java String rules.

String java(Object string)

Parameters
string
the string to escape values, may be null.
Returns
String with escaped values, null if null string input.

Delegates the process to StringEscapeUtils#escapeJava(String).

If $java had the following value:

He didn't say, "Stop!"

then the following Velocity script:

$esc.java($java)

produces this output:

He didn't say, \"Stop!\"


javascript()

Escapes the characters in a String using JavaScript String rules.

String javascript(Object string)

Parameters
string
the string to escape values, may be null.
Returns
String with escaped values, null if null string input.

Delegates the process to StringEscapeUtils#escapeJavaScript(String).

If $javascript had the following value:

He didn't say, "Stop!"

then the following Velocity script:

$esc.javascript($javascript)

produces this output:

He didn\'t say, \"Stop!\"


html()

Escapes the characters in a String using HTML entities.

String html(Object string)

Parameters
string
the string to escape values, may be null.
Returns
a new escaped String, null if null string input

Delegates the process to StringEscapeUtils#escapeHtml(String).

If $html had the following value:

"bread" & "butter"

then the following Velocity script:

$esc.html($html)

produces this output:

&quot;bread&quot; &amp; &quot;butter&quot;


$attrib.name

Escapes the characters in a String to be suitable to use as an HTTP parameter value.

String url(Object string)

Parameters
string
the string to escape values, may be null.
Returns
a new escaped String, null if null string input

Delegates the process to java.net.URLEncoder#encodeURL(String,"UTF-8").

If $url had the following value:

Hello here & there

then the following Velocity script:

$esc.url($url)

produces this output:

hello+here+%26+there


xml()

Escapes the characters in a String using XML entities.

String xml(Object string)

Parameters
string
the string to escape values, may be null.
Returns
a new escaped String, null if null string input

Delegates the process to StringEscapeUtils#escapeXml(String).

If $xml had the following value:

"bread" & "butter"

then the following Velocity script:

$esc.xml($xml)

produces this output:

&quot;bread&quot; &amp; &quot;butter&quot;


sql()

Escapes the characters in a String to be suitable to pass to an SQL query.

String sql(Object string)

Parameters
string
the string to escape values, may be null.
Returns
a new String, escaped for SQL, null if null string input

Delegates the process to StringEscapeUtils#escapeSql(String).

If $sql had the following value:

McHale's Navy

then the following Velocity script:

$esc.sql($sql)

produces this output:

McHale''s Navy


propertyKey()

Escapes the characters in a String using the rules for writing Java properties into a properties file.

String propertyKey(Object string)

Parameters
string
the string to escape values, may be null.
Returns
String with escaped values, null if null string input.

Taken directly from the private method dumpString of java.util.Properties from Apache Harmony. The only difference between this method and the propertyValue method below is; leading spaces will be escaped. If templating a substring of the key then use propertyValue below.

If $propertyKey had the following value:

 He didn't say, "Stop!":

then the following Velocity script:

$esc.propertyKey($propertyKey)

produces this output:

\ He didn't say, \"Stop!\"\:


propertyValue()

Escapes the characters in a String using the rules for Java properties.

String propertyValue(Object string)

Parameters
string
the string to escape values, may be null.
Returns
String with escaped values, null if null string input.

Taken directly from the private method dumpString of java.util.Properties from Apache Harmony.

If $propertyValue had the following value:

 He didn't say, "Stop!":

then the following Velocity script:

$esc.propertyValue($propertyValue)

produces this output:

 He didn't say, \"Stop!\"\:


getDollar()

Renders a dollar sign ($).

String getDollar()

Returns
a dollar sign ($).

The following Velocity script:

${esc.dollar}

produces this output:

$


getD()

Renders a dollar sign ($).

String getD()

Returns
a dollar sign ($).

The following Velocity script:

${esc.d}

produces this output:

$


getHash()

Renders a hash (#).

String getHash()

Returns
a hash (#).

The following Velocity script:

${esc.hash}

produces this output:

#


getH()

Renders a hash (#).

String getH()

Returns
a hash (#).

The following Velocity script:

${esc.h}

produces this output:

#


getBackslash()

Renders a backslash (\).

String getBackslash()

Returns
a backslash (\).

The following Velocity script:

${esc.backslash}

produces this output:

\


getB()

Renders a backslash (\).

String getB()

Returns
a backslash (\).

The following Velocity script:

${esc.b}

produces this output:

\


getQuote()

Renders a double quotation mark (").

String getQuote()

Returns
a double quotation mark (").

The following Velocity script:

${esc.quote}

produces this output:

"


getQ()

Renders a double quotation mark (").

String getQ()

Returns
a double quotation mark (").

The following Velocity script:

${esc.q}

produces this output:

"


getSingleQuote()

Renders a single quotation mark (').

String getSingleQuote()

Returns
a single quotation mark (').

The following Velocity script:

${esc.singleQuote}

produces this output:

'


getS()

Renders a single quotation mark (').

String getS()

Returns
a single quotation mark (').

The following Velocity script:

${esc.s}

produces this output:

'


getExclamation()

Renders an exclamation mark (!).

String getExclamation()

Returns
an exclamation mark (!).

The following Velocity script:

${esc.exclamation}

produces this output:

!


getE()

Renders an exclamation mark (!).

String getE()

Returns
an exclamation mark (!).

The following Velocity script:

${esc.e}

produces this output:

!



Copyright © 1999-2003, Apache Software Foundation