This project has retired. For details please refer to its Attic page.
Apache Tiles - Framework - Tiles Configuration Reference Fork me on GitHub

Configuring Tiles

Configuring Tiles means creating the following objects: * an instance of org.apache.tiles.request.ApplicationContext, * an instance of org.apache.tiles.TilesContainer. Usually these are created by an instance of org.apache.tiles.startup.TilesInitializer.

Several MVC frameworks (struts, spring, shale) provide an easy integration with tiles.

Starting Tiles in a web application

Tiles has always been a web application package, usually used in conjunction with Struts. Apache Tiles™ evolved to the point of being technology-independent, but its use in a Servlet-based web application will be the most frequent use case.

To start Tiles you can extend AbstractTilesListener and implement the createTilesInitializer method:

protected TilesInitializer createTilesInitializer() {
    return new MyCustomTilesInitializer();
}

You can use AbstractTilesInitializer as a basis.

Then you can start Tiles by specifing it in your web.xml file:

<listener>
    <listener-class>my.package.MyTilesListener</listener-class>
</listener>

Starting Tiles in a portlet application

TBD

Ready-made configuration classes

There are some classes that allows to play with Tiles without writing custom code.

Simple configuration

SimpleTilesListener or DefaultTilesInitializer are the "simple" way to load Tiles. This was the default for Tiles 2.1 and prior versions.

This configuration has the following characteristics:

  • loads the "/WEB-INF/tiles.xml" file;
  • allows support for JSP, Servlets and Portlets;
  • no expression language is allowed;
  • wildcard expressions can be used to declare definition names.

Feature-Complete configuration

It is possible to startup Tiles turning all the new features on by using CompleteAutoloadTilesListener or CompleteAutoloadTilesInitializer available in the tiles-extras module. This initializer turns on:

Modular initialization

It is possible to startup Tiles in a modular way, that is loading modules of independent Tiles configuration.

To turn it on, you need to use ModularTilesListener or ModularTilesInitializer available in the tiles-extras module.

Add in your manifest file, under the META-INF/MANIFEST.MF path, the Tiles-Initializer property, whose value is the name of the class of the needed initializer. For example:

Manifest-Version: 1.0
Tiles-Initializer: org.apache.tiles.extras.module.ModularTilesInitializerTest$TilesInitializer1

Every initializer that is found will be loaded and "initialized", and destroyed when the main initializer is destroyed.

Configuring Tiles internals

The container and the application context must be configured to allow custom behaviour and to load definitions from various sources.

Custom ApplicationContext

Custom ApplicationContext can be provided by implementing ApplicationContext. If you are under a servlet environment, you can override ServletApplicationContext.

To use it, you need to override the createTilesApplicationContext method of AbstractTilesInitializer.

The reason to use a custom Tiles application context could be:

  • supporting a platform not supported yet;
  • providing custom behaviour, such as loading resources in a different manner.

When loading resources (by default) an underscore in the name of a file is used to indicate locale information. See the documentation for localization.

Custom TilesContainerFactory

Custom Tiles containers can be created by custom Tiles container factories. You have to create a class that extends AbstractTilesContainerFactory. In particular you can use BasicTilesContainerFactory as a basis for your extended configuration. BasicTilesContainerFactory is the configuration that replicates the default configuration of Tiles, i.e. the one that assumes when no additional parameter is provided. The Javadoc documentation of BasicTilesContainerFactory documents all the methods that can be overridden to use your own configuration.

Changing the path for the Tiles Definitions file

The BasicTilesContainerFactory loads the "/WEB-INF/tiles.xml" file; the CompleteAutoloadTilesContainerFactory loads all the files named "tiles*.xml" under /WEB-INF and under every META-INF in any part of the classpath.

If this behaviour doesn't suits you, you can override the method getSources and retrieve whatever resource you prefer. Just specify the path for the default locale; Tiles will extrapolate and load the localized files as needed.

Custom components

These components can be used by overriding the appropriate create method in a custom TilesContainerFactory.

Custom LocaleResolver

The default implementation is DefaultLocaleResolver.

Custom DefinitionDAO

The default implementation is ResolvingLocaleUrlDefinitionDAO.

Custom AttributeEvaluatorFactory

The default implementation is BasicAttributeEvaluatorFactory.

It can be used with a number of AttributeEvaluators like:

Please see CompleteAutoloadTilesContainerFactory for an example of how to configure those.

Custom PreparerFactory

The default implementation is BasicPreparerFactory.

Currently the preparer is associated to a definition using its class name. There will be only one instance per unique class name. If you want to customize this behaviour, you have to create your own implementation of the PreparerFactory interface.

For example, the Struts 1 - Apache Tiles™ integration defines a PreparerFactory that can use a URL as a preparer.

Custom PatternDefinitionResolver

The default implementation is BasicPatternDefinitionResolver, that implements the wildcard syntax.

CompleteAutoloadTilesContainerFactory defines a PrefixedPatternDefinitionResolver to enable the use of both the wildcard syntax and the regexp syntax, with appropriate prefixes.

Registering Renderers

Custom Renderers can be registered by overriding the methods registerAttributeRenderers and createDefaultAttributeRenderer.

BasicTilesContainerFactory registers 3 renderers: string, template, and definition, in order to render plain strings, JSPs and tiles definitions.

CompleteAutoloadTilesContainerFactory registers 5 renderers: string, template, freemarker, velocity and definition, in order to render plain strings, JSPs, freemarker and velocity templates and tiles definitions.

Changing the definition files

The default implementation BasicTilesContainerFactory loads the file named /WEB-INF/tiles.xml.

CompleteAutoloadTilesContainerFactory loads all files named /WEB-INF/tiles*.xml in the web application, or /META-INF/tiles*.xml on the classpath.

Those file names can be changed by overriding the method getSources:

protected List<ApplicationResource> getSources(ApplicationContext applicationContext) {
    return applicationContext.getResources("/WEB-INF/my-tiles-definitions-file.xml");
}

Please note that when using CompleteAutoloadTilesContainerFactory, the ApplicationContext loads the resources via spring, and supports the spring syntax for locating resources.