| <?xml version="1.0"?> |
| <document url="./installation.xml"> |
| <properties> |
| <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><style></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://jakarta.apache.org/struts/"> |
| Jakarta 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><servlet> |
| </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> |
| <servlet> |
| ... |
| <servlet-name>action</servlet-name> |
| <servlet-class>org.apache.struts.tiles.ActionComponentsServlet</servlet-class |
| <init-param> |
| <param-name>definitions-config</param-name> |
| <param-value>/WEB-INF/tiles-config.xml</param-value> |
| </init-param> |
| ... |
| </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><taglib> |
| <taglib-uri>/WEB-INF/tiles.tld</taglib-uri> |
| <taglib-location>/WEB-INF/tiles.tld</taglib-location> |
| </taglib> |
| </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><%@ taglib uri="/WEB-INF/tiles.tld" prefix="tiles" %> |
| </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> |
| <controller processorClass="org.apache.struts.tiles.TilesRequestProcessor"> |
| </controller> |
| </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> |