~~ $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.
~~
         -----------
         Using multiple containers
         -----------

Defining multiple containers

  With Tiles 2.1 it is possible to use more that one Tiles container in your
  application.

* Configuration

  To use an alternate container, it must be configured through the use of the
  {{{../../config-reference.html#org.apache.tiles.startup.BasicTilesInitializer.CONTAINER_KEY}org.apache.tiles.startup.BasicTilesInitializer.CONTAINER_KEY}}
  initialization parameter. For example:

------------------------------------
<servlet>
    <servlet-name>tiles-alt</servlet-name>
    <servlet-class>org.apache.tiles.web.startup.TilesServlet</servlet-class>
    <init-param>
        <param-name>org.apache.tiles.startup.BasicTilesInitializer.CONTAINER_KEY</param-name>
        <param-value>alternate</param-value>
    </init-param>
</servlet>
------------------------------------

Selecting one non-default container

  Once defined, it is possible to select a non-default container through Java
  or JSP

* Selection through Java

  It is possible to use, for the current request, a different container
  stored under another key, by using
  {{{../../apidocs/org/apache/tiles/servlet/context/ServletUtil.html#setCurrentContainer(javax.servlet.ServletRequest,%20javax.servlet.ServletContext,%20org.apache.tiles.TilesContainer)}<<<setCurrentContainer>>>}}
  method of ServletUtil class. For example:

------------------------------------
ServletUtil.setCurrentContainer(request, applicationContext, "myContainerKey");
------------------------------------

  If the last parameter is <<<null>>>, the default container is selected.

* Selection through JSP

  The current container can be selected also through the use of JSP:

------------------------------------
<tiles:setCurrentContainer containerKey="myContainerKey" />
------------------------------------

  If the <<<containerKey>>> attribute is not present, the default container is selected.