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

Configuring Tiles

  Your application needs to be configured to work with Tiles. There are various
  options, depending on your needs, your application type, etc.
  
Starting Tiles in a web application

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

  To start Tiles you can use pure
  {{{configuration.html#Startup_with_Java_code}Java initialization}}
  or the original
  {{{configuration.html#Startup_with_initialization_parameters}initialization-parameter-based initialization}}.
  In both cases, you have two options, just choose what is the best for your
  needs:
  
  * Load the <<Tiles servlet>> at startup. You can do it by specifying it in
  your <<<web.xml>>> file:

--------------------------
<servlet>
    <servlet-name>tiles</servlet-name>
    <servlet-class>org.apache.tiles.web.startup.TilesServlet</servlet-class>
    ...
    <load-on-startup>2</load-on-startup>
</servlet>
--------------------------
  
  Note: The Tiles servlet is just a startup servlet and <<it does not serve any
  request>>. Therefore, a mapping is not needed.

  * Load the <<Tiles listener>>. Specify it in your <<<web.xml>>> file:

-------------------------------
<listener>
    <listener-class>org.apache.tiles.web.startup.TilesListener</listener-class>
</listener>
-------------------------------

** {Startup with Java code}

  To startup with Java code, extend <<<TilesListener>>> or <<<TilesServlet>>>
  and override the <<<createTilesServletInitializer>>> method:

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

** {Startup with initialization parameters}

  You can configure Tiles by using initialization parameters, like in Tiles 2.0.x.
  If you use <<<TilesServlet>>>, you can use <<<init-param>>> elements: 

--------------------------
<servlet>
    <servlet-name>tiles</servlet-name>
    <servlet-class>org.apache.tiles.web.startup.TilesServlet</servlet-class>
    <init-param>
        <param-name>
          org.apache.tiles.definition.DefinitionsFactory.DEFINITIONS_CONFIG
        </param-name>
        <param-value>
          /WEB-INF/tiles-defs.xml,/org/apache/tiles/classpath-defs.xml
        </param-value>
    </init-param>
    <load-on-startup>2</load-on-startup>
</servlet>
--------------------------

  As you can see, the init parameter
  <<<org.apache.tiles.definition.DefinitionsFactory.DEFINITIONS_CONFIG>>>
  specifies the path of the {{{basic/index.html}Tiles configuration files}}.
  You can specify it also as a context parameters.
  
  If you use <<<TilesListener>>>:

-------------------------------
<listener>
    <listener-class>org.apache.tiles.web.startup.TilesListener</listener-class>
</listener>
-------------------------------
  
  you can specify the Tiles configuration files using a context parameter:

-------------------------------
    <context-param>
        <param-name>
          org.apache.tiles.impl.BasicTilesContainer.DEFINITIONS_CONFIG
        </param-name>
        <param-value>
          /WEB-INF/tiles-defs.xml,/org/apache/tiles/classpath-defs.xml
        </param-value>
    </context-param>
-------------------------------

Starting Tiles in a portlet application 

  TBD

Configuring Tiles internals

* {Pure Java configuration}
  
  In both environments, it is possible to use pure <<Java configuration>>,
  without messing with the deployment descriptors. You have two choices of configuration:
  
  * By using a custom
  {{{../apidocs/org/apache/tiles/startup/TilesInitializer.html}TilesInitializer}},
  for example by overriding
  {{{../apidocs/org/apache/tiles/startup/BasicTilesInitializer.html}BasicTilesInitializer}}
  methods.
  
  * By using a subset of initialization parameters and extending
  {{{../apidocs/org/apache/tiles/factory/AbstractTilesContainerFactory.html}AbstractTilesContainerFactory}},
  {{{../apidocs/org/apache/tiles/context/AbstractTilesApplicationContextFactory.html}AbstractTilesApplicationContextFactory}}
  or both. This option can be combined with the first.

** Custom Tiles container factory

  You have to do 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.

  To enable pure Java configuration, provide the
  {{{../config-reference.html#org.apache.tiles.factory.AbstractTilesContainerFactory}<<<org.apache.tiles.factory.AbstractTilesContainerFactory>>>}}
  parameter this way:

--------------------------------
<init-param>
    <param-name>org.apache.tiles.factory.AbstractTilesContainerFactory</param-name>
    <param-value>org.apache.tiles.test.factory.TestTilesContainerFactory</param-value>
</init-param>
--------------------------------

  Where <<<TestTilesContainerFactory>>> is a class that extends
  <<<AbstractTilesContainerFactory>>>.

** Custom Tiles application context factory

  You have to do create a class that extends
  {{{../apidocs/org/apache/tiles/context/AbstractTilesApplicationContextFactory.html}AbstractTilesApplicationContextFactory}}
  In particular you can use
  {{{../apidocs/org/apache/tiles/servlet/context/ServletTilesApplicationContextFactory.html}ServletTilesApplicationContextFactory}}
  as a basis for your extended configuration under a servlet environment.
  
  To enable pure Java configuration for the Tiles application context, provide the
  {{{../config-reference.html#org.apache.tiles.context.AbstractTilesApplicationContextFactory}<<<org.apache.tiles.context.AbstractTilesApplicationContextFactory>>>}}
  parameter this way:

--------------------------------
<init-param>
    <param-name>org.apache.tiles.context.AbstractTilesApplicationContextFactory</param-name>
    <param-value>org.apache.tiles.test.context.TestTilesApplicationContextFactory</param-value>
</init-param>
--------------------------------

  Where <<<TestTilesApplicationContextFactory>>> is a class that extends
  <<<AbstractTilesApplicationContextFactory>>>.

* Configuration through initialization parameters

  You can configure Tiles internal behaviour by specifying:
  
  * in a web application environment, by using context parameters or init
  parameters of TilesServlet or TilesFilter;
  
  * in a portlet environment, by using portlet init parameters.
  
  For the details see {{{../config-reference.html}Tiles configuration reference}}.