Integration with Apache Velocity

Apache Velocity is a templating framework that can be used as a replacement for JavaServer Pages (JSP). Tiles can be used with Velocity through the use of Tiles Velocity package.

Configuration

To use Velocity together with Tiles

  • Add Velocity (1.7 or better) and Velocity Tools (2.0 or better) jars to your application.
  • Add tiles-template-x.x.x.jar and tiles-velocity-x.x.x.jar files to your application. * Add this code in you velocity.properties file:
    userdirective=org.apache.tiles.velocity.template.AddAttributeDirective,\
      org.apache.tiles.velocity.template.AddListAttributeDirective,\
      org.apache.tiles.velocity.template.DefinitionDirective,\
      org.apache.tiles.velocity.template.GetAsStringDirective,\
      org.apache.tiles.velocity.template.ImportAttributeDirective,\
      org.apache.tiles.velocity.template.InsertAttributeDirective,\
      org.apache.tiles.velocity.template.InsertDefinitionDirective,\
      org.apache.tiles.velocity.template.InsertTemplateDirective,\
      org.apache.tiles.velocity.template.PutAttributeDirective,\
      org.apache.tiles.velocity.template.PutListAttributeDirective
  • To access ".vm" files from HTTP requests, add this piece of configuration in web.xml (the parameters can be modified as needed).
    <servlet>
      <servlet-name>velocity</servlet-name>
      <servlet-class>org.apache.velocity.tools.view.VelocityViewServlet</servlet-class>
    
      <init-param>
        <param-name>org.apache.velocity.toolbox</param-name>
        <param-value>/WEB-INF/tools.xml</param-value>
      </init-param>
    
      <init-param>
        <param-name>org.apache.velocity.properties</param-name>
        <param-value>/WEB-INF/velocity.properties</param-value>
      </init-param>
    </servlet>
  • To access ".vm" files as attributes, register VelocityAttributeRenderer (only available in a servlet environment), by overriding the registerAttributeRenderers method in the AbstractTilesContainerFactory implementation being used, like:
    @Override
    protected void registerAttributeRenderers(
            BasicRendererFactory rendererFactory, TilesApplicationContext applicationContext,
            TilesRequestContextFactory contextFactory,
            TilesContainer container, AttributeEvaluator evaluator) {
        super.registerAttributeRenderers(rendererFactory, applicationContext, contextFactory,
                container, evaluator);
    
        VelocityAttributeRenderer velocityRenderer = new VelocityAttributeRenderer();
        velocityRenderer.setApplicationContext(applicationContext);
        velocityRenderer.setEvaluator(evaluator);
        velocityRenderer.setRequestContextFactory(contextFactory);
        velocityRenderer.setParameter("org.apache.velocity.toolbox", "/WEB-INF/tools.xml");
        velocityRenderer.setParameter("org.apache.velocity.properties", "/WEB-INF/velocity.properties");
        velocityRenderer.commit();
        rendererFactory.registerRenderer("velocity", velocityRenderer);
    }

    This way you can specify an attribute that is rendered directly using this syntax:

    <put-attribute name="myAttribute" value="/pages/myPage.vm" type="velocity" />

Usage in Velocity templates

There are two ways to use Tiles-Velocity integration:

  • the tiles tool, that is a Velocity-style tool:
    $tilesAlt.startAttributeContext()
    $set($templateAttribute = $tilesAlt.createTemplateAttribute("/page/myTemplate.vm"))
    $set($attributeContext = $tilesAlt.getAttributeContext())
      $set($attribute = $tilesAlt.createAttribute())
      $attribute.setValue("This is the title.")
      $attributeContext.putAttribute("title", $attribute})
    
      $set($attribute = $tilesAlt.createAttribute())
      $attribute.setValue("/velocity/header.vm")
      $attribute.setRenderer("velocity")
      $attributeContext.putAttribute("header", $attribute})
    
      $set($attribute = $tilesAlt.createAttribute())
      $attribute.setValue("/velocity/body.vm")
      $attribute.setRenderer("velocity")
      $attributeContext.putAttribute("body", $attribute})
    
    $tilesAlt.render($templateAttribute)
    $tilesAlt.endAttributeContext()
  • the tiles directives, that have a tag-like meaning.
    #tiles_insertTemplate({"template":"/page/myTemplate.vm"})
      #tiles_putAttribute({"name":"title", "value":"This is the title."})#end
      #tiles_putAttribute({"name":"header", "value":"/velocity/header.vm", "type":"velocity"})#end
      #tiles_putAttribute({"name":"body", "value":"/velocity/body.vm", "type":"velocity"})#end
    #end

    Other tiles directives are:

    • getAsString(String attributeName) - get the value of named attribute as string.
    • importAttribute(String attributeName, String toName) - import the named attribute into the scope of template context under the (optional) custom name.
    • insertAttribute(String attributeName) - inserts given attribute in the output in its own context. If this is a string a string is printed, if this is a definition - it is included in the output.
    • insertAttribute(String attributeName, boolean ownContext) - inserts given attribute in the output. If this is a string a string is printed, if this is a definition - it is included in the output. You can specify whether a separate context is created for rendering the definition - in this case variables with duplicate names will not be inherited from the parent definition
    • insertDefinition(String definitionName) - renders a definition in its own context.
    • insertDefinition(String definitionName, boolean ownContext) - inserts definition, optionally in the shared context.
    • insertTemplate(String template) - inserts a named page, equivalent to Velocity's #parse.

    For details about the tool and directives see the Javadocs.