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.
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>There are some classes that allows to play with Tiles without writing custom code.
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:
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:
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.
The container and the application context must be configured to allow custom behaviour and to load definitions from various sources.
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:
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 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.
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.
These components can be used by overriding the appropriate create method in a custom TilesContainerFactory.
The default implementation is DefaultLocaleResolver.
The default implementation is ResolvingLocaleUrlDefinitionDAO.
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.
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.
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.
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.
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.