src/site/apt/tutorial/configuration.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
         -----------

Configuring Tiles in your 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 is still the most frequent use case.

* Required libraries

  The first thing is to install the required libraries. For the purpose of this tutorial,
  we will install everything: the more we can do, the better. Just know that a 
  more "lightweight" but limited configuration is available.
  
  If you're using maven, just include this dependency, it will include the rest:
  
-------------
<groupId>org.apache.tiles</groupId>
<artifactId>tiles-extras</artifactId>
-------------  
  
  If you're not using maven, just {{{/download.html}download}} tiles and copy all the jars
  into the /WEB-INF/lib directory.

* Starting Tiles engine

  Load the tiles container by using the appropriate listener it in your <<<web.xml>>> file. Since we
  decided to load everything, we'll use <<<CompleteAutoloadTilesListener>>>:

-------------------------------
<listener>
    <listener-class>org.apache.tiles.extras.complete.CompleteAutoloadTilesListener</listener-class>
</listener>
-------------------------------

  For this tutorial, we'll configure Tiles to work directly with the servlet API, without a controller.
  In the real world, you'll probably use an MVC framework like Struts or Shale or Spring. You have to 
  configure your framework to work with Tiles; please refer to your framework's documentation for that. 
  For now, we'll just declare <<<TilesDispatchServlet>>> in <<<web.xml>>>:
  
-------------------------------
<servlet>
    <servlet-name>Tiles Dispatch Servlet</servlet-name>
    <servlet-class>org.apache.tiles.web.util.TilesDispatchServlet</servlet-class>
</servlet>
<servlet-mapping>
    <servlet-name>Tiles Dispatch Servlet</servlet-name>
    <url-pattern>*.tiles</url-pattern>
</servlet-mapping>
-------------------------------

  This means that any request to an URL ending in ".tiles" will be dispatched directly to the matching
  Tiles Definition.