src/site/apt/config-reference.apt

~~ $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
         -----------

Configuration reference

  In this page you can find a fast reference on configuring the various parts of
  Tiles. These configuration parameters can be used as context parameters of a
  web application, or as init parameters of servlets, filters or portlets.

Summary

* Standard configuration

  [[1]] {{{config-reference.html#Main_configuration}Main configuration}}.

*---------------------------------------------+--------------------------------------+
| {{{config-reference.html#org.apache.tiles.context.AbstractTilesApplicationContextFactory}<<<org.apache.tiles.context.AbstractTilesApplicationContextFactory>>>}}      | Tiles application context factory class name     |
*---------------------------------------------+--------------------------------------+
| {{{config-reference.html#org.apache.tiles.context.TilesRequestContextFactory}<<<org.apache.tiles.context.TilesRequestContextFactory>>>}}      | Tiles request context factory class name     |
*---------------------------------------------+--------------------------------------+
| {{{config-reference.html#org.apache.tiles.factory.AbstractTilesContainerFactory}<<<org.apache.tiles.factory.AbstractTilesContainerFactory>>>}}    | Class name of the container factory  |
*---------------------------------------------+--------------------------------------+
| {{{config-reference.html#org.apache.tiles.factory.TilesContainerFactory.MUTABLE}<<<org.apache.tiles.factory.TilesContainerFactory.MUTABLE>>>}} | Flag to use a mutable container |
*---------------------------------------------+--------------------------------------+
| {{{config-reference.html#org.apache.tiles.definition.DefinitionsFactory}<<<org.apache.tiles.definition.DefinitionsFactory>>>}}  | Definitions factory class name       |
*---------------------------------------------+--------------------------------------+
| {{{config-reference.html#org.apache.tiles.definition.DefinitionsFactory.DEFINITIONS_CONFIG}<<<org.apache.tiles.definition.DefinitionsFactory.DEFINITIONS_CONFIG>>>}}   | List of paths that contain Tiles definitions |
*---------------------------------------------+--------------------------------------+
| {{{config-reference.html#org.apache.tiles.evaluator.AttributeEvaluator}<<<org.apache.tiles.evaluator.AttributeEvaluator>>>}}  | Attribute evaluator class name       |
*---------------------------------------------+--------------------------------------+
| {{{config-reference.html#org.apache.tiles.preparer.PreparerFactory}<<<org.apache.tiles.preparer.PreparerFactory>>>}}     | View preparer factory class name     |
*---------------------------------------------+--------------------------------------+
| {{{config-reference.html#org.apache.tiles.renderer.RendererFactory}<<<org.apache.tiles.renderer.RendererFactory>>>}}     | Attribute renderer factory class name     |
*---------------------------------------------+--------------------------------------+
| {{{config-reference.html#org.apache.tiles.renderer.impl.BasicRendererFactory.TYPE_RENDERERS}<<<org.apache.tiles.renderer.impl.BasicRendererFactory.TYPE_RENDERERS>>>}}     | Attribute renderers class name     |
*---------------------------------------------+--------------------------------------+
| {{{config-reference.html#org.apache.tiles.renderer.impl.BasicRendererFactory.DEFAULT_RENDERER}<<<org.apache.tiles.renderer.impl.BasicRendererFactory.DEFAULT_RENDERER>>>}}     | Default attribute renderer class name     |
*---------------------------------------------+--------------------------------------+

  [[2]] {{{config-reference.html#ChainedTilesApplicationContextFactory_configuration}<<<ChainedTilesApplicationContextFactory>>> configuration}}.

*---------------------------------------------+--------------------------------------+
| {{{config-reference.html#org.apache.tiles.context.ChainedTilesApplicationContextFactory.FACTORY_CLASS_NAMES}<<<org.apache.tiles.context.ChainedTilesApplicationContextFactory.FACTORY_CLASS_NAMES>>>}} | List of elementary application factory class names |
*---------------------------------------------+--------------------------------------+

  [[3]] {{{config-reference.html#ChainedTilesRequestContextFactory_configuration}<<<ChainedTilesRequestContextFactory>>> configuration}}.

*---------------------------------------------+--------------------------------------+
| {{{config-reference.html#org.apache.tiles.context.ChainedTilesRequestContextFactory.FACTORY_CLASS_NAMES}<<<org.apache.tiles.context.ChainedTilesRequestContextFactory.FACTORY_CLASS_NAMES>>>}} | List of elementary request factory class names |
*---------------------------------------------+--------------------------------------+

  [[4]] {{{config-reference.html#DigesterDefinitionsReader_configuration}<<<DigesterDefinitionsReader>>> configuration}}.

*---------------------------------------------+--------------------------------------+
| {{{config-reference.html#org.apache.tiles.definition.digester.DigesterDefinitionsReader.PARSER_VALIDATE}<<<org.apache.tiles.definition.digester.DigesterDefinitionsReader.PARSER_VALIDATE>>>}} | Flag to deactivate XML parser validation |
*---------------------------------------------+--------------------------------------+

  [[5]] {{{config-reference.html#UrlDefinitionsFactory_configuration}<<<UrlDefinitionsFactory>>> configuration}}.

*---------------------------------------------+--------------------------------------+
| {{{config-reference.html#org.apache.tiles.definition.DefinitionsReader}<<<org.apache.tiles.definition.DefinitionsReader>>>}} | Definitions reader class name |
*---------------------------------------------+--------------------------------------+
| {{{config-reference.html#org.apache.tiles.locale.LocaleResolver}<<<org.apache.tiles.locale.LocaleResolver>>>}} | Locale resolver class name          |
*---------------------------------------------+--------------------------------------+

  [[6]] {{{config-reference.html#Initialization_configuration}<<<Initialization>>> configuration}}.

*---------------------------------------------+--------------------------------------+
| {{{config-reference.html#org.apache.tiles.startup.BasicTilesInitializer.CONTAINER_KEY}<<<org.apache.tiles.startup.BasicTilesInitializer.CONTAINER_KEY>>>}} | Container key |
*---------------------------------------------+--------------------------------------+

* Extended configuration

  [[1]] {{{config-reference.html#KeyedDefinitionsFactoryTilesContainerFactory_configuration}<<<KeyedDefinitionsFactoryTilesContainerFactory>>> configuration}}.

*---------------------------------------------+--------------------------------------+
| {{{config-reference.html#org.apache.tiles.impl.KeyedDefinitionsFactoryTilesContainer.KeyExtractor}<<<org.apache.tiles.impl.KeyedDefinitionsFactoryTilesContainer.KeyExtractor>>>}} | Key extractor class name           |
*---------------------------------------------+--------------------------------------+
| {{{config-reference.html#org.apache.tiles.factory.KeyedDefinitionsFactoryTilesContainerFactory.KEYS}<<<org.apache.tiles.factory.KeyedDefinitionsFactoryTilesContainerFactory.KEYS>>>}} | List of keys to be used              |
*---------------------------------------------+--------------------------------------+
| {{{config-reference.html#org.apache.tiles.DEFINITIONS_CONFIG@$\{key\}}<<<org.apache.tiles.DEFINITIONS_CONFIG@$\{key\}>>>}} | List of paths containing definitions for the given <<<key>>> |
*---------------------------------------------+--------------------------------------+

* Deprecated configuration

  The following configuration parameters are deprecated:

  * <<<org.apache.tiles.context.ChainedTilesContextFactory.FACTORY_CLASS_NAMES>>>: use
  {{{config-reference.html#org.apache.tiles.context.ChainedTilesApplicationContextFactory.FACTORY_CLASS_NAMES}<<<org.apache.tiles.context.ChainedTilesApplicationContextFactory.FACTORY_CLASS_NAMES>>>}}
  or
  {{{config-reference.html#org.apache.tiles.context.ChainedTilesRequestContextFactory.FACTORY_CLASS_NAMES}<<<org.apache.tiles.context.ChainedTilesRequestContextFactory.FACTORY_CLASS_NAMES>>>}}

  * <<<org.apache.tiles.context.TilesContextFactory>>>: use
  {{{config-reference.html#org.apache.tiles.context.AbstractTilesApplicationContextFactory}<<<org.apache.tiles.context.AbstractTilesApplicationContextFactory>>>}}
  or
  {{{config-reference.html#org.apache.tiles.context.TilesRequestContextFactory}<<<org.apache.tiles.context.TilesRequestContextFactory>>>}}

  * <<<org.apache.tiles.factory.TilesContainerFactory>>>: use
  {{{config-reference.html#org.apache.tiles.factory.AbstractTilesContainerFactory}<<<org.apache.tiles.factory.AbstractTilesContainerFactory>>>}}

  * <<<org.apache.tiles.impl.BasicTilesContainer.DEFINITIONS_CONFIG>>>: use
  {{{config-reference.html#org.apache.tiles.definition.DefinitionsFactory.DEFINITIONS_CONFIG}<<<org.apache.tiles.definition.DefinitionsFactory.DEFINITIONS_CONFIG>>>}}

Standard configuration parameters

* {Main configuration}

** {<<<org.apache.tiles.context.AbstractTilesApplicationContextFactory>>>}

  Specifies the application context factory class name to use.
  
  * <<Specified in>>:
  {{{apidocs/org/apache/tiles/context/AbstractTilesApplicationContextFactory.html#APPLICATION_CONTEXT_FACTORY_INIT_PARAM}<<<org.apache.tiles.context.AbstractTilesApplicationContextFactory>>>}}.
    
  * <<Default>>: <<<org.apache.tiles.context.ChainedTilesApplicationContextFactory>>>.
    
  * <<Usage>>: when specified, it must contain the name of a class that
  implements the <<<AbstractTilesApplicationContextFactory>>> interface.

** {<<<org.apache.tiles.context.TilesRequestContextFactory>>>}

  Specifies the request context factory class name to use.
  
  * <<Specified in>>:
  {{{apidocs/org/apache/tiles/factory/TilesContainerFactory.html#REQUEST_CONTEXT_FACTORY_INIT_PARAM}<<<org.apache.tiles.factory.TilesContainerFactory>>>}}.
    
  * <<Default>>: <<<org.apache.tiles.context.ChainedTilesRequestContextFactory>>>.
    
  * <<Usage>>: when specified, it must contain the name of a class that
  implements the <<<TilesRequestContextFactory>>> interface.

** {<<<org.apache.tiles.factory.AbstractTilesContainerFactory>>>}

  Specifies the container factory class name to use.
  
  * <<Specified in>>:
  {{{apidocs/org/apache/tiles/factory/AbstractTilesContainerFactory.html#CONTAINER_FACTORY_INIT_PARAM}<<<org.apache.tiles.factory.AbstractTilesContainerFactory>>>}}.
    
  * <<Default>>: <<<org.apache.tiles.factory.TilesContainerFactory>>>.
    
  * <<Usage>>: when specified, it must contain the name of a class that
  extends the <<<AbstractTilesContainerFactory>>> class.

** {<<<org.apache.tiles.factory.TilesContainerFactory.MUTABLE>>>}

  Flag to use a mutable container.
  
  * <<Specified in>>:
  {{{apidocs/org/apache/tiles/factory/TilesContainerFactory.html#CONTAINER_FACTORY_MUTABLE_INIT_PARAM}<<<org.apache.tiles.factory.TilesContainerFactory>>>}}.
    
  * <<Default>>: <<<false>>> (the container is not mutable).
    
  * <<Usage>>: when specified and when its value is <<<true>>>, the container to
  be created will be <mutable>, i.e. definitions can be created at runtime.

** {<<<org.apache.tiles.definition.DefinitionsFactory>>>}

  Specifies the context factory class name to use.
  
  * <<Specified in>>:
  {{{apidocs/org/apache/tiles/factory/TilesContainerFactory.html#DEFINITIONS_FACTORY_INIT_PARAM}<<<org.apache.tiles.factory.TilesContainerFactory>>>}}.
    
  * <<Default>>: <<<org.apache.tiles.definition.UrlDefinitionsFactory>>>.
    
  * <<Usage>>: when specified, it must contain the name of a class that
  implements the <<<DefinitionsFactory>>> interface.

** {<<<org.apache.tiles.evaluator.AttributeEvaluator>>>}

  Specifies the attribute evaluator class name to use.
  
  * <<Specified in>>:
  {{{apidocs/org/apache/tiles/factory/TilesContainerFactory.html#ATTRIBUTE_EVALUATOR_INIT_PARAM}<<<org.apache.tiles.factory.TilesContainerFactory>>>}}.
    
  * <<Default>>: <<<org.apache.tiles.evaluator.impl.DirectAttributeEvaluator>>>.
    
  * <<Usage>>: when specified, it must contain the name of a class that
  implements the <<<AttributeEvaluator>>> interface.

** {<<<org.apache.tiles.preparer.PreparerFactory>>>}

  Specifies the view preparer factory class name to use.
  
  * <<Specified in>>:
  {{{apidocs/org/apache/tiles/factory/TilesContainerFactory.html#PREPARER_FACTORY_INIT_PARAM}<<<org.apache.tiles.factory.TilesContainerFactory>>>}}.
    
  * <<Default>>: <<<org.apache.tiles.preparer.BasicPreparerFactory>>>.
    
  * <<Usage>>: when specified, it must contain the name of a class that
  implements the <<<PreparerFactory>>> interface.

** {<<<org.apache.tiles.renderer.RendererFactory>>>}

  Specify the class of the attribute renderer factory to use.
  
  * <<Specified in>>:
  {{{apidocs/org/apache/tiles/factory/TilesContainerFactory.html#RENDERER_FACTORY_INIT_PARAM}<<<org.apache.tiles.factory.TilesContainerFactory>>>}}.
    
  * <<Default>>: <<<org.apache.tiles.renderer.impl.BasicRendererFactory>>>
    
  * <<Usage>>: when specified, it must contain the class name of the attribute
  renderer factory to use.

** {<<<org.apache.tiles.renderer.impl.BasicRendererFactory.TYPE_RENDERERS>>>}

  Specifies the named attribute renderers that can be used.
  
  * <<Specified in>>:
  {{{apidocs/org/apache/tiles/renderer/impl/BasicRendererFactory.html#TYPE_RENDERERS_INIT_PARAM}<<<org.apache.tiles.renderer.impl.BasicRendererFactory>>>}}.
    
  * <<Default>>: <<<string,org.apache.tiles.renderer.impl.StringAttributeRenderer;
  definition,org.apache.tiles.renderer.impl.DefinitionAttributeRenderer;
  template,org.apache.tiles.renderer.impl.TemplateAttributeRenderer>>>.
    
  * <<Usage>>: when specified, it must contain a semicolon (;) separated list
  of comma-separated pairs (,) in which:

  ** the first element is the name of the renderer;

  ** the second element is the class name of the attribute renderer.

** {<<<org.apache.tiles.renderer.impl.BasicRendererFactory.DEFAULT_RENDERER>>>}

  Specifies the named attribute renderers that can be used.
  
  * <<Specified in>>:
  {{{apidocs/org/apache/tiles/renderer/impl/BasicRendererFactory.html#DEFAULT_RENDERER_INIT_PARAM}<<<org.apache.tiles.renderer.impl.BasicRendererFactory>>>}}.
    
  * <<Default>>: <<<org.apache.tiles.renderer.impl.UntypedAttributeRenderer>>>
    
  * <<Usage>>: when specified, it must contain the class name of the attribute
  renderer to use in case the type of an attribute is not specified.

* {<<<BasicTilesContainer>>> configuration}

** {<<<org.apache.tiles.definition.DefinitionsFactory.DEFINITIONS_CONFIG>>>}

  Specifies the list of files that contain the definitions.
  
  * <<Specified in>>:
  {{{apidocs/org/apache/tiles/definition/DefinitionsFactory.html#DEFINITIONS_CONFIG}<<<org.apache.tiles.definition.DefinitionsFactory>>>}}.
    
  * <<Default>>: <<</WEB-INF/tiles.xml>>>.
    
  * <<Usage>>: when specified, it must contain a comma-separated list of paths
  of files that contain Tiles definitions.

* {<<<ChainedTilesApplicationContextFactory>>> configuration}

** {<<<org.apache.tiles.context.ChainedTilesApplicationContextFactory.FACTORY_CLASS_NAMES>>>}

  Specifies the list of elementary Tiles application context factory class names.
  
  * <<Specified in>>:
  {{{apidocs/org/apache/tiles/context/ChainedTilesApplicationContextFactory.html#FACTORY_CLASS_NAMES}<<<org.apache.tiles.context.ChainedTilesApplicationContextFactory>>>}}.
    
  * <<Default>>: <<<org.apache.tiles.servlet.context.ServletTilesApplicationContextFactory,
  org.apache.tiles.portlet.context.PortletApplicationTilesApplicationContextFactory>>>
    
  * <<Usage>>: when specified, it must contain a comma-separated list of class
  names extending
  {{{apidocs/org/apache/tiles/context/AbstractTilesApplicationContextFactory.html}<<<AbstractTilesApplicationContextFactory>>>}}.

* {<<<ChainedTilesRequestContextFactory>>> configuration}

** {<<<org.apache.tiles.context.ChainedTilesRequestContextFactory.FACTORY_CLASS_NAMES>>>}

  Specifies the list of elementary Tiles request context factory class names.
  
  * <<Specified in>>:
  {{{apidocs/org/apache/tiles/context/ChainedTilesRequestContextFactory.html#FACTORY_CLASS_NAMES}<<<org.apache.tiles.context.ChainedTilesRequestContextFactory>>>}}.
    
  * <<Default>>: <<<org.apache.tiles.servlet.context.ServletTilesRequestContextFactory,
  org.apache.tiles.portlet.context.PortletTilesRequestContextFactory,
  org.apache.tiles.jsp.context.JspTilesRequestContextFactory>>>
    
  * <<Usage>>: when specified, it must contain a comma-separated list of class
  names implementing
  {{{apidocs/org/apache/tiles/context/TilesRequestContextFactory.html}<<<TilesRequestContextFactory>>>}}.
  
* {<<<DigesterDefinitionsReader>>> configuration}

** {<<<org.apache.tiles.definition.digester.DigesterDefinitionsReader.PARSER_VALIDATE>>>}

  Specifies if the digester should validate input XML files.
  
  * <<Specified in>>:
  {{{apidocs/org/apache/tiles/definition/digester/DigesterDefinitionsReader.html#PARSER_VALIDATE_PARAMETER_NAME}<<<org.apache.tiles.definition.digester.DigesterDefinitionsReader>>>}}.
    
  * <<Default>>: <<<true>>>
    
  * <<Usage>>: when specified, it must be <<<true>>> if you want to enable
  validation, <<<false>>> otherwise..
  
* {<<<UrlDefinitionsFactory>>> configuration}

** {<<<org.apache.tiles.definition.DefinitionsReader>>>}

  Specifies the implementation of
  {{{apidocs/org/apache/tiles/definition/DefinitionsReader.html}<<<DefinitionsReader>>>}}
  to use.
  
  * <<Specified in>>:
  {{{apidocs/constant-values.html#org.apache.tiles.definition.DefinitionsFactory.READER_IMPL_PROPERTY}<<<org.apache.tiles.definition.DefinitionsFactory>>>}}.
    
  * <<Default>>: <<<org.apache.tiles.definition.digester.DigesterDefinitionsReader>>>
    
  * <<Usage>>: when specified, it must contain the name of a class implementing
  {{{apidocs/org/apache/tiles/definition/DefinitionsReader.html}<<<DefinitionsReader>>>}}.

** {<<<org.apache.tiles.locale.LocaleResolver>>>}

  Specifies the implementation of
  {{{apidocs/org/apache/tiles/locale/LocaleResolver.html}<<<LocaleResolver>>>}}
  to use.
  
  * <<Specified in>>:
  {{{apidocs/constant-values.html#org.apache.tiles.definition.DefinitionsFactory.LOCALE_RESOLVER_IMPL_PROPERTY}<<<org.apache.tiles.definition.DefinitionsFactory>>>}}.
    
  * <<Default>>: <<<org.apache.tiles.locale.impl.DefaultLocaleResolver>>>
    
  * <<Usage>>: when specified, it must contain the name of a class implementing
  {{{apidocs/org/apache/tiles/locale/LocaleResolver.html}<<<LocaleResolver>>>}}.

* {Initialization configuration}

** {<<<org.apache.tiles.startup.BasicTilesInitializer.CONTAINER_KEY>>>}

  Specifies the key under which the Tiles container will be stored. 

  * <<Specified in>>:
  {{{apidocs/org/apache/tiles/startup/BasicTilesInitializer.html#CONTAINER_KEY_INIT_PARAMETER}<<<org.apache.tiles.startup.BasicTilesInitializer>>>}}.

  * <<Default>>: <<<null>>> (default container)

  * <<Usage>>: when specified, it must contain the key under which the container
  will be stored.

Extended configuration parameters
  
* {<<<KeyedDefinitionsFactoryTilesContainerFactory>>> configuration}

** {<<<org.apache.tiles.impl.KeyedDefinitionsFactoryTilesContainer.KeyExtractor>>>}

  Specifies the implementation of
  {{{apidocs/org/apache/tiles/impl/KeyedDefinitionsFactoryTilesContainer.KeyExtractor.html}<<<KeyExtractor>>>}}
  to use.
  
  * <<Specified in>>:
  {{{apidocs/org/apache/tiles/factory/KeyedDefinitionsFactoryTilesContainerFactory.html#KEY_EXTRACTOR_CLASS_INIT_PARAM}<<<org.apache.tiles.factory.KeyedDefinitionsFactoryTilesContainerFactory>>>}}.
    
  * <<Default>>: <<<org.apache.tiles.impl.KeyedDefinitionsFactoryTilesContainer.DefaultKeyExtractor>>>
    
  * <<Usage>>: when specified, it must contain the name of a class implementing
  {{{apidocs/org/apache/tiles/impl/KeyedDefinitionsFactoryTilesContainer.KeyExtractor.html}<<<KeyExtractor>>>}}.

** {<<<org.apache.tiles.factory.KeyedDefinitionsFactoryTilesContainerFactory.KEYS>>>}

  Specifies the list of keys to be used to assign a key to each Definitions
  Factory.
  
  * <<Specified in>>:
  {{{apidocs/org/apache/tiles/factory/KeyedDefinitionsFactoryTilesContainerFactory.html#CONTAINER_KEYS_INIT_PARAM}<<<org.apache.tiles.factory.KeyedDefinitionsFactoryTilesContainerFactory>>>}}.
    
  * <<Default>>: None, it must be specified explicitly.
    
  * <<Usage>>: when specified, it must contain a comma-separated list of keys
  to be used to assign a key to each definitions factory.

** {<<<org.apache.tiles.DEFINITIONS_CONFIG@$\{key\}>>>}

  Specifies the list of files that contain the definitions for the corresponding
  <<<$\{key\}>>>.
  
  * <<Specified in>>:
  {{{apidocs/org/apache/tiles/impl/KeyedDefinitionsFactoryTilesContainer.html#DEFINITIONS_CONFIG_PREFIX}<<<org.apache.tiles.impl.KeyedDefinitionsFactoryTilesContainer>>>}}.
    
  * <<Default>>: <<</WEB-INF/tiles.xml>>>.
    
  * <<Usage>>:  when specified, it must contain a comma-separated list of paths
  of files that contain Tiles definitions to assign to the needed
  <<<$\{key\}>>>.