Package org.apache.velocity.tools.struts

Class TilesTool

  • @DefaultKey("tiles")
@ValidScope("request")
public class TilesTool
extends ImportSupport

    The TilesTool is used to interact with the Struts-Tiles framework that is part of Struts 1.

     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:
 <tools>
   <toolbox scope="request">
     <tool class="org.apache.velocity.tools.struts.TilesTool"/>
   </toolbox>
 </tools>

    This tool may only be used in the request scope.

    Since:
    VelocityTools 1.1
    Version:
    $Revision$ $Date$
    Author:
    Marino A. Jonsson

    • Field Detail

      • velocityContext

        protected org.apache.velocity.context.Context velocityContext

      • contextStack

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

      • catchExceptions

        protected boolean catchExceptions
        Indicates if there is a MethodExceptionEventHandler present

    • Constructor Detail

      • TilesTool

        public TilesTool()

    • Method Detail

      • setVelocityContext

        public void setVelocityContext​(org.apache.velocity.context.Context context)
        Initializes this tool.
        Parameters:
        context - the current Context
        Throws:
        IllegalArgumentException - if the param is not a Context

      • setCatchExceptions

        public void setCatchExceptions​(boolean catchExceptions)

      • get

        public String get​(Object obj)
           throws Exception
        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:
        Exception - on failure

      • getAttribute

        public Object getAttribute​(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​(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​(String name,
                            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​(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 String processObjectValue​(Object value)
                             throws 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:
        Exception - - Throws by underlying nested call to processDefinitionName()

      • processTypedAttribute

        protected String processTypedAttribute​(org.apache.struts.tiles.AttributeDefinition value)
                                throws Exception
        Process typed attribute according to its type.
        Parameters:
        value - Typed attribute to process.
        Returns:
        the fully processed attribute value as String.
        Throws:
        Exception - - Throws by underlying nested call to processDefinitionName()

      • processAsDefinitionOrURL

        protected String processAsDefinitionOrURL​(String name)
                                   throws 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:
        Exception

      • processDefinition

        protected String processDefinition​(org.apache.struts.tiles.ComponentDefinition definition)
                            throws Exception
        End of Process for definition.
        Parameters:
        definition - Definition to process.
        Returns:
        the fully processed definition.
        Throws:
        Exception - from InstantiationException Can't create requested controller

      • processUrl

        protected String processUrl​(String url)
                     throws Exception
        Processes an url
        Parameters:
        url - the URI to process.
        Returns:
        the rendered template as String.
        Throws:
        Exception

      • doInsert

        protected String doInsert​(String page,
                          String role,
                          org.apache.struts.tiles.Controller controller)
                   throws 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:
        Exception

      • doInsert

        protected String doInsert​(Map attributes,
                          String page,
                          String role,
                          org.apache.struts.tiles.Controller controller)
                   throws 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:
        Exception

      • doInsert

        protected String doInsert​(org.apache.struts.tiles.ComponentContext subCompContext,
                          String page,
                          String role,
                          org.apache.struts.tiles.Controller controller)
                   throws 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:
        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.