| ~~ $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 |
| ~~ |
| ~~ http://www.apache.org/licenses/LICENSE-2.0 |
| ~~ |
| ~~ Unless required by applicable law or agreed to in writing, |
| ~~ software distributed under the License is distributed on an |
| ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| ~~ 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 |
| {{{./apidocs/org/apache/tiles/web/startup/AbstractTilesListener.html}AbstractTilesListener}} |
| 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: |
| |
| ------------------------------- |
| <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 |
| |
| {{{./apidocs/org/apache/tiles/web/startup/simple/SimpleTilesListener.html}SimpleTilesListener}} |
| or |
| {{{./apidocs/org/apache/tiles/startup/DefaultTilesInitializer.html}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 |
| {{{./apidocs/org/apache/tiles/extras/complete/CompleteAutoloadTilesListener.html}CompleteAutoloadTilesListener}} |
| or |
| {{{./apidocs/org/apache/tiles/extras/complete/CompleteAutoloadTilesInitializer.html}CompleteAutoloadTilesInitializer}} |
| 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 |
| {{{./apidocs/org/apache/tiles/extras/module/ModularTilesListener.html}ModularTilesListener}} |
| or |
| {{{./apidocs/org/apache/tiles/extras/module/ModularTilesInitializer.html}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 |
| {{{/tiles-request/apidocs/org/apache/tiles/request/ApplicationContext.html}ApplicationContext}}. |
| If you are under a servlet environment, you can override |
| {{{/tiles-request/apidocs/org/apache/tiles/request/servlet/ServletApplicationContext.html}ServletApplicationContext}}. |
| |
| To use it, you need to override the |
| {{{./apidocs/org/apache/tiles/startup/AbstractTilesInitializer.html#method_summary}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 {{{/tiles-request/apidocs/org/apache/tiles/request/locale/PostfixedApplicationResource.html}default}}) |
| an underscore in the name of a file is used to indicate locale information. |
| See the documentation for {{{/framework/tutorial/advanced/l10n.html}localization}}. |
| |
| * Custom {TilesContainerFactory} |
| |
| Custom Tiles containers can be created by custom Tiles container factories. |
| You have to create a class that extends |
| {{{./apidocs/org/apache/tiles/factory/AbstractTilesContainerFactory.html}AbstractTilesContainerFactory}}. |
| 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. |
| The |
| {{{./apidocs/org/apache/tiles/factory/BasicTilesContainerFactory.html}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 {{{./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 |
| {{{http://static.springsource.org/spring/docs/2.5.x/reference/resources.html#resources-resource-strings}the spring syntax}} for locating resources. |
| |