<?xml version="1.0"?>
<document url="./installation.xml">
<properties>
    <author>Craig R. McClanahan</author>
    <author>Martin Cooper</author>
    <author>Ted Husted</author>
    <author>Cedric Dumoulin</author>
  <title>The Tiles 1.1 Framework Project - Installation (1.1)</title>
</properties>

<body>

<section name="Quick Install for Testing, Documentation and Tutorial"
         href="QuickInstall">
    <ul>
        <li>Download Tiles binary distribution</li>
        <li>Unzip distribution</li>
        <li>Copy <code>web/tiles-doc.war</code> or <code>web/struts-tiles.war</code>
            in  your web server webapps directory (webapps with Tomcat).
            Please refer to your webserver manual to know exactly where, or
            check <a href="#Containers">detailed install</a>.</li>
        <li>Restart your web server if necessary</li>
        <li>Point your browser to the root of newly installed web application
            (<a href="http://localhost:8080/tiles-doc">
            http://localhost:8080/tiles-doc</a>
             or <a href="http://localhost:8080/struts-tiles">
             http://localhost:8080/struts-tiles</a>
            with tomcat</li>
    </ul>

    <p>Quick start and setting of a new application using Tiles</p>
    <ul>
        <li>Take appropriate <code>tiles-blank.war</code> and
            copy it in your web server webapps directory
            <ul>
                <li><code>tiles-blank.war</code> - Tiles
                    without Struts</li>
                <li><code>tiles-blank-struts1.1.war</code> -
                    Tiles with Struts1.1</li>
                <li><code>tiles-blank-struts1.0.war</code> -
                    Tiles with latest stable Struts1.0.x</li>
            </ul>
        </li>
        <li>These war files are not distributed with Struts binaries.</li>
    </ul>
</section>

<section name="Prerequisite Software" href="Prerequisites">
    <p>Copyright : This page is largely inspired from the original
       <a href="http://jakarta.apache.org/struts">Struts installation page</a>.
       For those familiar with Struts, there is nothing really new.</p>

    <p>The Tiles binary distribution needs other software packages installed
       to operate. You may already have these installed on your system. To
       build Tiles from source you may need to acquire and install several
       others. The complete list is as follows:</p>

    <ul>
        <li><strong>Java Development Kit</strong> -
            You <strong>must</strong> download and install a Java2 (version
            1.2 or later) Java Development Kit implementation for your
            operating system platform. A good starting point for locating Java
            Development Kit distributions is <a href="http://java.sun.com/j2se">
            http://java.sun.com/j2se</a>.
        </li>
        <li><strong>Servlet Container</strong> -
            You <strong>must</strong> download and install a servlet container
            that is compatible with the Servlet API Specification, version 2.2
            or later, and the JavaServer Pages (JSP) Specification, version 1.1
            or later. One popular choice is to download Apache's
            <a href="http://jakarta.apache.org/tomcat">Tomcat</a>
            (version 3.1 or later required, version 3.2 or later recommended).</li>
        <li><strong>XML Parser</strong> - Tiles <strong>requires</strong> the
            presence of an XML parser that is compatible with the Java API for
            XML Parsing (JAXP) specification, 1.1 or later. You can download
            and install the JAXP <a href="http://java.sun.com/xml">reference
            implementation</a>, which is required for building the Tiles
            source distribution. In Tiles-based web applications, you may
            replace the reference implementation classes with any other JAXP
            compliant parser, such as <a href="http://xml.apache.org/xerces-j">
            Xerces</a>. See detailed    instructions related to the parser in
            the instructions for <a href="#Building">building</a> and
            <a href="#Installing">installing</a> Tiles, below. </li>
        <li><strong>Ant Build System</strong> -
            If you are building Tiles from the source distribution, you must
            download and install version 1.3 or later of the
            <a href="http://jakarta.apache.org/ant">Ant</a> build system.
            This package is also strongly recommended for use in developing
            your own web applications based on Tiles.
        <ul>
            <li>If you are using the release version of Ant version 1.3, you
                will also need to download the "optional.jar" file that
                contains the implementation of Ant's <code>&lt;style&gt;</code>
                command. </li>
            <li>Make sure that the "ant" and "ant.bat" scripts
                are executable, by adding the $ANT_HOME/bin directory to your
                PATH environment variable. </li>
        </ul>
        </li>
        <li><strong>Servlet API Classes</strong> - In order to compile Tiles
            itself, or applications that use Tiles, you will need a
            <code>servlet.jar</code> file containing the Servlet and JSP API
            classes. Most servlet containers include this JAR file. Otherwise,
            you can get the Servlet API classes distribution from
            <a href="http://jakarta.apache.org/builds/jakarta-servletapi">
            here</a>.
        </li>
        <li><strong>Jakarta Commons Packages</strong> -
            Tiles utilizes several    packages from the
            <a href="http://jakarta.apache.org/commons/">Jakarta Commons
            Project</a>.If you are utilizing a binary distribution of Tiles,
            the corresponding JAR files are included in the <code>lib</code>
            directory. However, if you wish to build Tiles from source, you
            will need to download and install the following packages:

        <ul>
                <li><em>Beanutils</em> (Version 1.0 or later)</li>
                <li><em>Collections</em> (Version 1.0 or later)</li>
                <li><em>Digester</em> (Version 1.0 or later)</li>
                <li><em>Logging</em> (Version 1.0 or later)</li>
        </ul>
        </li>
        <li><strong>Xalan XSLT Processor</strong> -
            If you are building Tiles from the source distribution, you will
            need a version of Xalan to perform XSLT transformations. If you
            are using the JAXP/1.1 XML parser, you    should use the version
            of <code>xalan.jar</code> shipped with it. Otherwise, download
            and install version 1.2 of Xalan from
            <a href="http://xml.apache.org/xalan">here</a>.
        </li>
        <li><strong>Struts Framework</strong> - If you are planning to use
            Tiles with Struts, you should download and install Struts from
            <a href="http://struts.apache.org/">
            Apache Struts Project</a>.
            If you have acquired Tiles with the Struts distribution, you
            don't need to install it again. Tiles can run without Struts.
            In this case you loose some features.</li>
    </ul>
</section>

<section name="Install A Tiles Binary Distribution" href="Installing">
    <p>First, download a binary distribution of Tiles by following the
       instructions <a href="download.jsp">here</a>.
       Then, make sure    you have downloaded and installed the
       <a href="#Prerequisites">prerequisite</a> software packages described
       above.</p>
    <p>Unpack the Tiles binary distribution into a convenient directory.
       (If you <a href="#Building">build Tiles from the source distribution</a>,
       the result of the build will already be an unpacked binary distribution
       for you). The distribution consists of the following contents:</p>
    <ul>
        <li><strong>lib/tiles.jar</strong> - This JAR file contains all of
            the Java classes included in Tiles. It should be copied into the
            <code>WEB-INF/lib</code>directory of your web application.
            <em>WARNING</em> - If you are going to be hosting multiple tiles
            based applications on the same servlet container, you will be
            tempted to place the <code>struts.jar</code> file into the shared
            repository supported by your container. Be advised that this will
            likely cause you to encounter ClassNotFoundException problems
            unless <em>all</em> of your application classes are stored in the
            shared repository.
        </li>
        <li><strong>lib/struts1.0/tilesForStruts1.0.jar</strong> -
            Same as before,    but for use with Struts1.0.x. </li>
        <li><strong>lib/tiles.tld</strong> - These is the "tag library
            descriptor" file that describe the custom tags in the Tiles tag
            libraries. It should be copied into the <code>WEB-INF</code>
            directory of your web application.
        </li>
        <li><strong>webapps/tiles-doc.war</strong> or
            <strong>webapps/struts-tiles.war</strong> - This is a
            "web application archive" file containing all of the Tiles
            documentation found on the
            <a href="http://www.lifl.fr/~dumoulin/tiles/">Tiles web site</a>
            (including these pages). You can install this web application
            on any servlet container compatible with Servlet API 2.2 or later.
        </li>
        <li><strong>webapps/tiles-channel.war</strong> - Examples using a
            custom definition factory.</li>
        <li><strong>webapps/tiles-blank.war</strong> - A blank application
            that can be used as a starting point when you want to develop
            your own application with Tiles. This blank application doesn't
            contains neither use Struts. If you also want to use Struts,
            add struts.jar and related tld files, or choose one of the
            following applications. </li>
        <li><strong>webapps/tiles-blank-struts1.1.war</strong> -
            A blank application to use with Struts1.1 </li>
        <li><strong>webapps/tiles-blank-struts1.0.war</strong> -
            A blank application to use with Struts1.0.x </li>
    </ul>
    <p>To use Tiles in your own application, you will need to follow
       these steps:</p>
    <ul>
        <li>Copy the files<code>lib/commons-*.jar</code> into
            the <code>WEB-INF/lib</code> directory of your web application.
        </li>
        <li>Copy the file <code>lib/tiles.jar</code> from
            the Tiles distribution    into the <code>WEB-INF/lib</code>
            directory of your web application.
        </li>
        <li>Copy all of the files that match <code>lib/*.tld</code> from
            the Tiles    distribution into the <code>WEB-INF</code> directory
            of your web application.
        </li>
        <li>If you want to use <em>definitions configuration file</em>, you
            need to initialize the definitions factory. This can be done as follows:
        <ul>
            <li>Modify the <code>WEB-INF/web.xml</code> file
                for your web application to use a <code>&lt;servlet&gt;
                </code> that initializes the factory and catch Struts action
                forwards to check for definition name. Use the
                <code>WEB-INF/web.xml</code> file from the Tiles example
                application for a detailed example of the required syntax.
            <pre>
  &lt;servlet&gt;
     ...
     &lt;servlet-name&gt;action&lt;/servlet-name&gt;
     &lt;servlet-class&gt;org.apache.struts.tiles.ActionComponentsServlet&lt;/servlet-class
     &lt;init-param&gt;
       &lt;param-name&gt;definitions-config&lt;/param-name&gt;
       &lt;param-value&gt;/WEB-INF/tiles-config.xml&lt;/param-value&gt;
     &lt;/init-param&gt;
     ...
</pre>
            </li>
            <li>If you don't want to use Struts, use
                <code>org.apache.struts.tiles.TilesServlet</code> as servlet.
            </li>
            <li>Create a configuration file for definitions. Its name must
                match the one provided before in <code>WEB-INF/web.xml</code>.
                Several comma separated names can be provided.
            </li>
        </ul>
        </li>
        <li>Modify the <code>WEB-INF/web.xml</code> file of your web application
            to include the following tag library declarations: </li>
    </ul>
<pre>&lt;taglib&gt;
  &lt;taglib-uri&gt;/WEB-INF/tiles.tld&lt;/taglib-uri&gt;
  &lt;taglib-location&gt;/WEB-INF/tiles.tld&lt;/taglib-location&gt;
&lt;/taglib&gt;
</pre>

    <ul>
        <li>At the top of each JSP page that will use the Tiles custom tags,
            add line(s) declaring the Tiles custom tag libraries used on this
            particular page, like this:</li>
    </ul>
<pre>&lt;%@ taglib uri="/WEB-INF/tiles.tld" prefix="tiles" %&gt;
</pre>
    <ul>
        <li>When compiling the Java classes that comprise your application,
            be sure to include the <code>tiles.jar</code> and
            <code>commons-*.jar</code> files (copied earlier) on the
            CLASSPATH that is submitted to the compiler.</li>
    </ul>
    <p>Note to Struts 1.0 users :</p>
    <ul>
        <li>You should use a <code>tiles.jar</code> build with Struts1.0.x.</li>
        <li>If you have downloaded a Tiles version build with Struts1.0.x, you
            already have it. </li>
        <li>Consider to use tilesForStruts1.0.jar located in
            <code>lib/struts1.0</code></li>
    </ul>

    <p>Note to Struts1.1 users :</p>
    <ul>
        <li>You should also initialize a <code>TilesRequestProcessor</code>.</li>
        <li>To do so, add following lines in your <code>struts-config.xml</code>
            file :
<pre>
   &lt;controller processorClass="org.apache.struts.tiles.TilesRequestProcessor"&gt;
   &lt;/controller&gt;
</pre>
        </li>
    </ul>
</section>

<section name="Installing Tiles with your servlet container" href="Containers">
    <p><strong>WARNING</strong> - Do <strong>NOT</strong> add
       <code>tiles.jar</code> to the classpath of your servlet container in
       an attempt to avoid placing it in the <code>/WEB-INF/lib</code>
       directory of each individual web app! Doing so will cause problems with
       <code>ClassNotFoundException</code> exceptions. </p>

    <p>For most containers, you need only to:</p>
    <ul>
        <li>Copy the WAR files in your Tiles <code>/webapp</code> directory
            to your    containers <code>webapps</code> directory. </li>
        <li>In some cases, you may need to restart your container if it
            is running.</li>
    </ul>

    <h4>Status of various containers</h4>
    <p>For status of additional containers, please refer to the
        <a href="installation.html#Installing"> Struts installation page</a>).
    </p>
</section>

<section name="Building Tiles From Source" href="Building">
    <p>First, download a source distribution of Tiles from
       <a href="http://www.lifl.fr/~dumoulin/tiles/">here</a> or
       from Struts contrib directory. Then, make sure you have downloaded and
       installed <strong>all</strong> of the
       <a href="#Prerequisites">prerequisite</a> software packages described
       above. You also need the appropriate struts version (1.0.x or 1.1)</p>
    <p>To build Tiles, you will need to customize the build process to the details
        of your development environment as follows: </p>
    <ul>
        <li>The Tiles source distribution uses a file named
            <code>build.properties</code> (in the top-level directory of the
            distribution) to identify the location of external components
            that Tiles depends on.</li>
        <li>There is no <code>build.properties</code> file included with the
            source distribution. However, there is an example file named
            <code>build.properties.example</code> that you can copy to
            <code>build.properties</code>and then customize.</li>
        <li>The properties you must configure in <code>build.properties</code> are
            documented in <code>build.properties.example</code> </li>
        <li>Tiles build require a Struts library. You can use either a
            Struts1.0.x or 1.1 <code>struts.jar</code>. The resulting
            <code>tiles.jar</code> will run with the used <code>struts.jar</code>.
            You specify the Struts home with <code>struts.home</code> property.
        </li>
    </ul>
    <p>To build a "distribution" version of Tiles, first change your current
        directory to the directory in which you have unpacked the Tiles
        source distribution, and (if necessary) create or customize the
        <code>build.properties</code>file as described above. Then, type:
    </p>
<pre>
        ant dist
</pre>

    <p>This command will create a binary distribution of Tiles, in a
       directory named <code>dist</code> (relative to where you are
       compiling from). This directory contains an exact replica of
       the files included in a binary distribution of Tiles, as described
       in the <a href="Installing">preceding section</a>.</p>
    <p>IMPORTANT NOTE: The <code>tiles.jar</code>, as well as the JAR
        files from the Jakarta Commons project, must be in your classpath
        when compiling Tiles. The <code>build.xml</code> provided does this
        automatically. If you use your development machine to test Tiles
        application locally, be sure that the <code>tiles.jar</code>is
        <strong>NOT</strong> on your classpath when your container is
        running.
    </p>
</section>
</body>
</document>