org.apache.velocity.tools.struts
Class TilesTool

java.lang.Object
  org.apache.velocity.tools.view.ImportSupport
      org.apache.velocity.tools.struts.TilesTool

All Implemented Interfaces:

ViewTool

public class TilesTool

extends ImportSupport

implements ViewTool

View tool to use struts-tiles with Velocity.

 Template example(s):
  <!-- insert a tile -->
  $tiles.myTileDefinition

  <!-- get named attribute value from the current tiles-context -->
  $tiles.getAttribute("myTileAttribute")

  <!-- import all attributes of the current tiles-context into the velocity-context. -->
  $tiles.importAttributes()

 Toolbox configuration:
 <tool>
   <key>tiles</key>
   <scope>request</scope>
   <class>org.apache.velocity.tools.struts.TilesTool</class>
 </tool>
 

This tool should only be used in the request scope.

Since:

VelocityTools 1.1

Version:

$Revision: 329695 $ $Date: 2005-10-30 17:34:08 -0800 (Sun, 30 Oct 2005) $

Author:

Marino A. Jonsson

Nested Class Summary

Nested classes inherited from class org.apache.velocity.tools.view.ImportSupport

ImportSupport.ImportResponseWrapper

Field Summary

(package private) static java.lang.String	APPLICATION_SCOPE
protected java.util.Stack	contextStack A stack to hold ComponentContexts while nested tile-definitions are rendered.
protected static org.apache.commons.logging.Log	LOG
(package private) static java.lang.String	PAGE_SCOPE
(package private) static java.lang.String	REQUEST_SCOPE
(package private) static java.lang.String	SESSION_SCOPE
protected org.apache.velocity.context.Context	velocityContext

Fields inherited from class org.apache.velocity.tools.view.ImportSupport

application, DEFAULT_ENCODING, isAbsoluteUrl, request, response, VALID_SCHEME_CHARS

Constructor Summary

TilesTool()
Default constructor.

Method Summary

protected java.lang.String	doInsert(org.apache.struts.tiles.ComponentContext subCompContext, java.lang.String page, java.lang.String role, org.apache.struts.tiles.Controller controller) An extension of the other two doInsert functions
protected java.lang.String	doInsert(java.util.Map attributes, java.lang.String page, java.lang.String role, org.apache.struts.tiles.Controller controller) Use this if there is a nested tile.
protected java.lang.String	doInsert(java.lang.String page, java.lang.String role, org.apache.struts.tiles.Controller controller) Use this if there is no nested tile.
java.lang.String	get(java.lang.Object obj) A generic tiles insert function.
java.lang.Object	getAttribute(java.lang.String name) Fetches a named attribute-value from the current tiles-context.
protected org.apache.struts.tiles.ComponentContext	getCurrentContext() Retrieve the current tiles component context.
void	importAttribute(java.lang.String name) Imports the named attribute-value from the current tiles-context into the current Velocity context.
void	importAttribute(java.lang.String name, java.lang.String scope) Imports the named attribute-value from the current tiles-context into the named context ("page", "request", "session", or "application").
void	importAttributes() Imports all attributes in the current tiles-context into the current velocity-context.
void	importAttributes(java.lang.String scope) Imports all attributes in the current tiles-context into the named context ("page", "request", "session", or "application").
void	init(java.lang.Object obj) Initializes this tool.
protected void	popTilesContext() Pops the tiles sub-context off the context-stack after the lower level tiles have been rendered.
protected java.lang.String	processAsDefinitionOrURL(java.lang.String name) Try to process name as a definition, or as an URL if not found.
protected java.lang.String	processDefinition(org.apache.struts.tiles.ComponentDefinition definition) End of Process for definition.
protected java.lang.String	processObjectValue(java.lang.Object value) Process an object retrieved as a bean or attribute.
protected java.lang.String	processTypedAttribute(org.apache.struts.tiles.AttributeDefinition value) Process typed attribute according to its type.
protected java.lang.String	processUrl(java.lang.String url) Processes an url
protected void	pushTilesContext() pushes the current tiles context onto the context-stack.

Methods inherited from class org.apache.velocity.tools.view.ImportSupport

acquireReader, acquireString, getContentTypeAttribute, isAbsoluteUrl, stripSession

Methods inherited from class java.lang.Object

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

Field Detail

LOG

protected static final org.apache.commons.logging.Log LOG

PAGE_SCOPE

static final java.lang.String PAGE_SCOPE

See Also:

Constant Field Values

REQUEST_SCOPE

static final java.lang.String REQUEST_SCOPE

See Also:

Constant Field Values

SESSION_SCOPE

static final java.lang.String SESSION_SCOPE

See Also:

Constant Field Values

APPLICATION_SCOPE

static final java.lang.String APPLICATION_SCOPE

See Also:

Constant Field Values

velocityContext

protected org.apache.velocity.context.Context velocityContext

contextStack

protected java.util.Stack contextStack

A stack to hold ComponentContexts while nested tile-definitions are rendered.

Constructor Detail

TilesTool

public TilesTool()

Default constructor. Tool must be initialized before use.

Method Detail

init

public void init(java.lang.Object obj)

Initializes this tool.

Specified by:

init in interface ViewTool

Parameters:

obj - the current ViewContext

Throws:

java.lang.IllegalArgumentException - if the param is not a ViewContext

get

public java.lang.String get(java.lang.Object obj)

A generic tiles insert function.

This is functionally equivalent to <tiles:insert attribute="foo" />.

Parameters:

obj - Can be any of the following: AttributeDefinition, tile-definition name, tile-attribute name, regular uri. (checked in that order)

Returns:

the rendered template or value as a String

Throws:

java.lang.Exception - on failure

getAttribute

public java.lang.Object getAttribute(java.lang.String name)

Fetches a named attribute-value from the current tiles-context.

This is functionally equivalent to <tiles:getAsString name="foo" />.

Parameters:

name - the name of the tiles-attribute to fetch

Returns:

attribute value for the named attribute

importAttribute

public void importAttribute(java.lang.String name)

Imports the named attribute-value from the current tiles-context into the current Velocity context.

This is functionally equivalent to <tiles:importAttribute name="foo" />

Parameters:

name - the name of the tiles-attribute to import

importAttribute

public void importAttribute(java.lang.String name,
                            java.lang.String scope)

Imports the named attribute-value from the current tiles-context into the named context ("page", "request", "session", or "application").

This is functionally equivalent to <tiles:importAttribute name="foo" scope="scopeValue" />

Parameters:

name - the name of the tiles-attribute to import

scope - the named context scope to put the attribute into.

importAttributes

public void importAttributes()

Imports all attributes in the current tiles-context into the current velocity-context.

This is functionally equivalent to <tiles:importAttribute />.

importAttributes

public void importAttributes(java.lang.String scope)

Imports all attributes in the current tiles-context into the named context ("page", "request", "session", or "application").

This is functionally equivalent to <tiles:importAttribute scope="scopeValue" />.

Parameters:

scope - the named context scope to put the attributes into.

processObjectValue

protected java.lang.String processObjectValue(java.lang.Object value)
                                       throws java.lang.Exception

Process an object retrieved as a bean or attribute.

Parameters:

value - - Object can be a typed attribute, a String, or anything else. If typed attribute, use associated type. Otherwise, apply toString() on object, and use returned string as a name.

Returns:

the fully processed value as String

Throws:

java.lang.Exception - - Throws by underlying nested call to processDefinitionName()

processTypedAttribute

protected java.lang.String processTypedAttribute(org.apache.struts.tiles.AttributeDefinition value)
                                          throws java.lang.Exception

Process typed attribute according to its type.

Parameters:

value - Typed attribute to process.

Returns:

the fully processed attribute value as String.

Throws:

java.lang.Exception - - Throws by underlying nested call to processDefinitionName()

processAsDefinitionOrURL

protected java.lang.String processAsDefinitionOrURL(java.lang.String name)
                                             throws java.lang.Exception

Try to process name as a definition, or as an URL if not found.

Parameters:

name - Name to process.

Returns:

the fully processed definition or URL

Throws:

java.lang.Exception

processDefinition

protected java.lang.String processDefinition(org.apache.struts.tiles.ComponentDefinition definition)
                                      throws java.lang.Exception

End of Process for definition.

Parameters:

definition - Definition to process.

Returns:

the fully processed definition.

Throws:

java.lang.Exception - from InstantiationException Can't create requested controller

processUrl

protected java.lang.String processUrl(java.lang.String url)
                               throws java.lang.Exception

Processes an url

Parameters:

url - the URI to process.

Returns:

the rendered template as String.

Throws:

java.lang.Exception

doInsert

protected java.lang.String doInsert(java.lang.String page,
                                    java.lang.String role,
                                    org.apache.struts.tiles.Controller controller)
                             throws java.lang.Exception

Use this if there is no nested tile.

Parameters:

page - the page to process.

role - possible user-role

controller - possible tiles-controller

Returns:

the rendered template as String.

Throws:

java.lang.Exception

doInsert

protected java.lang.String doInsert(java.util.Map attributes,
                                    java.lang.String page,
                                    java.lang.String role,
                                    org.apache.struts.tiles.Controller controller)
                             throws java.lang.Exception

Use this if there is a nested tile.

Parameters:

attributes - attributes for the sub-context

page - the page to process.

role - possible user-role

controller - possible tiles-controller

Returns:

the rendered template as String.

Throws:

java.lang.Exception

doInsert

protected java.lang.String doInsert(org.apache.struts.tiles.ComponentContext subCompContext,
                                    java.lang.String page,
                                    java.lang.String role,
                                    org.apache.struts.tiles.Controller controller)
                             throws java.lang.Exception

An extension of the other two doInsert functions

Parameters:

subCompContext - the sub-context to set in scope when the template is rendered.

page - the page to process.

role - possible user-role

controller - possible tiles-controller

Returns:

the rendered template as String.

Throws:

java.lang.Exception

getCurrentContext

protected org.apache.struts.tiles.ComponentContext getCurrentContext()

Retrieve the current tiles component context. This is pretty much just a convenience method.

pushTilesContext

protected void pushTilesContext()

pushes the current tiles context onto the context-stack. preserving the context is necessary so that a sub-context can be put into request scope and lower level tiles can be rendered

popTilesContext

protected void popTilesContext()

Pops the tiles sub-context off the context-stack after the lower level tiles have been rendered.