blob: 71a7b6dcecfac5c1d9aa6dd0f2a496096ba252fa [file] [log] [blame]
~~ $Id$
~~ Licensed to the Apache Software Foundation (ASF) under one
~~ or more contributor license agreements. See the NOTICE file
~~ distributed with this work for additional information
~~ regarding copyright ownership. The ASF licenses this file
~~ to you under the Apache License, Version 2.0 (the
~~ "License"); you may not use this file except in compliance
~~ with the License. You may obtain a copy of the License at
~~ Unless required by applicable law or agreed to in writing,
~~ software distributed under the License is distributed on an
~~ KIND, either express or implied. See the License for the
~~ specific language governing permissions and limitations
~~ under the License.
Tiles Configuration Reference
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\u0099 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
and implement the <<<createTilesInitializer>>> method:
protected TilesInitializer createTilesInitializer() {
return new MyCustomTilesInitializer();
You can use {{{./apidocs/org/apache/tiles/startup/AbstractTilesInitializer.html}AbstractTilesInitializer}}
as a basis.
Then you can start Tiles by specifing it in your <<<web.xml>>> file:
* Starting Tiles in a portlet application
{Ready-made configuration classes}
There are some classes that allows to play with Tiles without writing custom code.
* Simple configuration
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
available in the <<<tiles-extras>>> module. This initializer turns on:
* {{{./tutorial/integration/freemarker.html}Freemarker}} and {{{./tutorial/integration/velocity.html}Velocity}} support;
* using EL, OGNL and MVEL as {{{./tutorial/advanced/el-support.html}evaluation languages}};
* using Wildcards and Regular expression as {{{./tutorial/advanced/wildcard.html}pattern matching languages}};
* loading {{{./migration/configuration.html#Reusing_old_Tiles_configuration_files}Tiles 1.x definition files}};
* loads all the files named "tiles*.xml" under /WEB-INF and under every META-INF in any part of the classpath.
* using a mutable container to create Definitions at runtime.
* 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
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
If you are under a servlet environment, you can override
To use it, you need to override the
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.
* Custom {TilesContainerFactory}
Custom Tiles containers can be created by custom Tiles container factories.
You have to create a class that extends
In particular you can use {{{./apidocs/org/apache/tiles/factory/BasicTilesContainerFactory.html}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.
{{{./apidocs/org/apache/tiles/factory/BasicTilesContainerFactory.html}Javadoc documentation of BasicTilesContainerFactory}}
documents all the methods that can be overridden to use your own
** 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 {{{./apidocs/org/apache/tiles/locale/impl/DefaultLocaleResolver.html}DefaultLocaleResolver}}.
** Custom {DefinitionDAO}
The default implementation is {{{./apidocs/org/apache/tiles/definition/dao/ResolvingLocaleUrlDefinitionDAO.html}ResolvingLocaleUrlDefinitionDAO}}.
** Custom {AttributeEvaluatorFactory}
The default implementation is {{{./apidocs/org/apache/tiles/evaluator/BasicAttributeEvaluatorFactory.html}BasicAttributeEvaluatorFactory}}.
It can be used with a number of AttributeEvaluators like:
* the {{{./apidocs/org/apache/tiles/evaluator/impl/DirectAttributeEvaluator.html}DirectAttributeEvaluator}},
* the {{{./apidocs/org/apache/tiles/el/ELAttributeEvaluator.html}ELAttributeEvaluator}},
* the {{{./apidocs/org/apache/tiles/mvel/MVELAttributeEvaluator.html}MVELAttributeEvaluator}},
* the {{{./apidocs/org/apache/tiles/ognl/OGNLAttributeEvaluator.html}OGNLAttributeEvaluator}}.
Please see {{{./xref/org/apache/tiles/extras/complete/CompleteAutoloadTilesContainerFactory.html}CompleteAutoloadTilesContainerFactory}}
for an example of how to configure those.
** Custom {PreparerFactory}
The default implementation is {{{./apidocs/org/apache/tiles/preparer/factory/BasicPreparerFactory.html}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 {{{./tutorial/integration/frameworks.html}Struts 1 - Apache Tiles\u0099 integration}}
defines a <<<PreparerFactory>>> that can use a URL as a preparer.
** Custom {PatternDefinitionResolver}
The default implementation is {{{./apidocs/org/apache/tiles/definition/pattern/BasicPatternDefinitionResolver.html}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 {{{/tiles-request/apidocs/org/apache/tiles/request/render/Renderer.html}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.