org.apache.velocity.tools.generic
Class RenderTool

java.lang.Object
  org.apache.velocity.tools.generic.RenderTool

Direct Known Subclasses:

ViewRenderTool

public class RenderTool
extends java.lang.Object

This tool exposes methods to evaluate the given strings as VTL (Velocity Template Language) using the given context.

NOTE: These examples assume you have placed an instance of the current context within itself as 'ctx'. And, of course, the RenderTool is assumed to be available as 'render'.

 Example of eval():
      Input
      -----
      #set( $list = [1,2,3] )
      #set( $object = '$list' )
      #set( $method = 'size()' )
      $render.eval($ctx, "${object}.$method")

      Output
      ------
      3

 Example of recurse():
      Input
      -----
      #macro( say_hi )hello world!#end
      #set( $foo = '#say_hi()' )
      #set( $bar = '$foo' )
      $render.recurse($ctx, $bar)

      Output
      ------
      hello world!


 Toolbox configuration:
 <tool>
   <key>render</key>
   <class>org.apache.velocity.tools.generic.RenderTool</class>
 </tool>
 

Ok, so these examples are really lame. But, it seems like someone out there is always asking how to do stuff like this and we always tell them to write a tool. Now we can just tell them to use this tool.

This tool is safe (and optimized) for use in the application scope of a servlet environment.

Version:

$Revision: 588792 $ $Date: 2007-10-26 16:11:34 -0700 (Fri, 26 Oct 2007) $

Author:

Nathan Bubna

Field Summary

private boolean	catchExceptions
static int	DEFAULT_PARSE_DEPTH The maximum number of loops allowed when recursing.
private org.apache.velocity.app.VelocityEngine	engine
static java.lang.String	KEY_CATCH_EXCEPTIONS
static java.lang.String	KEY_PARSE_DEPTH
private static java.lang.String	LOG_TAG
private int	parseDepth

Constructor Summary

RenderTool()

Method Summary

void	configure(java.util.Map params) Looks for parse depth and catch.exceptions parameters.
java.lang.String	eval(org.apache.velocity.context.Context ctx, java.lang.String vtl) Evaluates a String containing VTL using the current context, and returns the result as a String.
boolean	getCatchExceptions() Returns true if this render() and eval() methods will catch exceptions thrown during rendering.
int	getParseDepth() Get the maximum number of loops allowed when recursing.
private java.lang.String	internalEval(org.apache.velocity.context.Context ctx, java.lang.String vtl)
protected java.lang.String	internalRecurse(org.apache.velocity.context.Context ctx, java.lang.String vtl, int count)
java.lang.String	recurse(org.apache.velocity.context.Context ctx, java.lang.String vtl) Recursively evaluates a String containing VTL using the current context, and returns the result as a String.
void	setCatchExceptions(boolean catchExceptions) Sets whether or not the render() and eval() methods should catch exceptions during their execution or not.
void	setParseDepth(int depth) Set the maximum number of loops allowed when recursing.
void	setVelocityEngine(org.apache.velocity.app.VelocityEngine ve) Allow user to specify a VelocityEngine to be used in place of the Velocity singleton.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_PARSE_DEPTH

public static final int DEFAULT_PARSE_DEPTH

The maximum number of loops allowed when recursing.

Since:

VelocityTools 1.2

See Also:

Constant Field Values

KEY_PARSE_DEPTH

public static final java.lang.String KEY_PARSE_DEPTH

See Also:

Constant Field Values

KEY_CATCH_EXCEPTIONS

public static final java.lang.String KEY_CATCH_EXCEPTIONS

See Also:

Constant Field Values

LOG_TAG

private static final java.lang.String LOG_TAG

See Also:

Constant Field Values

engine

private org.apache.velocity.app.VelocityEngine engine

parseDepth

private int parseDepth

catchExceptions

private boolean catchExceptions

Constructor Detail

RenderTool

public RenderTool()

Method Detail

configure

public void configure(java.util.Map params)

Looks for parse depth and catch.exceptions parameters.

Since:

VelocityTools 1.3

setVelocityEngine

public void setVelocityEngine(org.apache.velocity.app.VelocityEngine ve)

Allow user to specify a VelocityEngine to be used in place of the Velocity singleton.

setParseDepth

public void setParseDepth(int depth)

Set the maximum number of loops allowed when recursing.

Since:

VelocityTools 1.2

getParseDepth

public int getParseDepth()

Get the maximum number of loops allowed when recursing.

Since:

VelocityTools 1.2

setCatchExceptions

public void setCatchExceptions(boolean catchExceptions)

Sets whether or not the render() and eval() methods should catch exceptions during their execution or not.

Since:

VelocityTools 1.3

getCatchExceptions

public boolean getCatchExceptions()

Returns true if this render() and eval() methods will catch exceptions thrown during rendering.

Since:

VelocityTools 1.3

eval

public java.lang.String eval(org.apache.velocity.context.Context ctx,
                             java.lang.String vtl)
                      throws java.lang.Exception

Evaluates a String containing VTL using the current context, and returns the result as a String. By default if this fails, then null will be returned, though this tool can be configured to let Exceptions pass through. This evaluation is not recursive.

Parameters:

ctx - the current Context

vtl - the code to be evaluated

Returns:

the evaluated code as a String

Throws:

java.lang.Exception

internalEval

private java.lang.String internalEval(org.apache.velocity.context.Context ctx,
                                      java.lang.String vtl)
                               throws java.lang.Exception

Throws:

java.lang.Exception

recurse

public java.lang.String recurse(org.apache.velocity.context.Context ctx,
                                java.lang.String vtl)
                         throws java.lang.Exception

Recursively evaluates a String containing VTL using the current context, and returns the result as a String. It will continue to re-evaluate the output of the last evaluation until an evaluation returns the same code that was fed into it or the number of recursive loops exceeds the set parse depth.

Parameters:

ctx - the current Context

vtl - the code to be evaluated

Returns:

the evaluated code as a String

Throws:

java.lang.Exception

internalRecurse

protected java.lang.String internalRecurse(org.apache.velocity.context.Context ctx,
                                           java.lang.String vtl,
                                           int count)
                                    throws java.lang.Exception

Throws:

java.lang.Exception