Apache Tiles - Framework - Integration with Apache Velocity

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 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 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.