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.
  • 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 this way (only available in a servlet environment):
    @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 Velocity tools that will be available to your application:

  • the tilesAlt 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.renderAttribute($templateAttribute)
$tilesAlt.endAttributeContext()
  • the tiles tool, that has both Velocity-style methods and directive oriented methods.
    $tiles.insertTemplate.start({"template":"/page/myTemplate.vm"})
  $tiles.putAttribute({"name":"title", "value":"This is the title."})
  $tiles.putAttribute({"name":"header", "value":"/velocity/header.vm", "type":"velocity"})
  $tiles.putAttribute({"name":"body", "value":"/velocity/body.vm", "type":"velocity"})
$tiles.insertTemplate().end()

    For details about directives see the Javadocs.