Quick Install for Testing, Documentation and Tutorial
- Download Tiles binary distribution
- Unzip distribution
- Copy
web/tiles-doc.war
orweb/struts-tiles.war
in your web server webapps directory (webapps with Tomcat). Please refer to your webserver manual to know exactly where, or check detailed install. - Restart your web server if necessary
- Point your browser to the root of newly installed web application ( http://localhost:8080/tiles-doc or http://localhost:8080/struts-tiles with tomcat
Quick start and setting of a new application using Tiles
- Take appropriate
tiles-blank.war
and copy it in your web server webapps directory-
tiles-blank.war
- Tiles without Struts -
tiles-blank-struts1.1.war
- Tiles with Struts1.1 -
tiles-blank-struts1.0.war
- Tiles with latest stable Struts1.0.x
-
- These war files are not distributed with Struts binaries.
Prerequisite Software
Copyright : This page is largely inspired from the original Struts installation page. For those familiar with Struts, there is nothing really new.
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:
- Java Development Kit - You must 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 http://java.sun.com/j2se.
- Servlet Container - You must 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 Tomcat (version 3.1 or later required, version 3.2 or later recommended).
- XML Parser - Tiles requires 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 reference implementation, 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 Xerces. See detailed instructions related to the parser in the instructions for building and installing Tiles, below.
-
Ant Build System -
If you are building Tiles from the source distribution, you must
download and install version 1.3 or later of the
Ant build system.
This package is also strongly recommended for use in developing
your own web applications based on Tiles.
- 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
<style>
command. - Make sure that the "ant" and "ant.bat" scripts are executable, by adding the $ANT_HOME/bin directory to your PATH environment variable.
- 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
-
Servlet API Classes - In order to compile Tiles
itself, or applications that use Tiles, you will need a
servlet.jar
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 here. -
Jakarta Commons Packages -
Tiles utilizes several packages from the
Jakarta Commons
Project.If you are utilizing a binary distribution of Tiles,
the corresponding JAR files are included in the
lib
directory. However, if you wish to build Tiles from source, you will need to download and install the following packages:- Beanutils (Version 1.0 or later)
- Collections (Version 1.0 or later)
- Digester (Version 1.0 or later)
- Logging (Version 1.0 or later)
-
Xalan XSLT Processor -
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
xalan.jar
shipped with it. Otherwise, download and install version 1.2 of Xalan from here. - Struts Framework - If you are planning to use Tiles with Struts, you should download and install Struts from Apache Struts Project. 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.
Install A Tiles Binary Distribution
First, download a binary distribution of Tiles by following the instructions here. Then, make sure you have downloaded and installed the prerequisite software packages described above.
Unpack the Tiles binary distribution into a convenient directory. (If you build Tiles from the source distribution, the result of the build will already be an unpacked binary distribution for you). The distribution consists of the following contents:
-
lib/tiles.jar - This JAR file contains all of
the Java classes included in Tiles. It should be copied into the
WEB-INF/lib
directory of your web application. WARNING - If you are going to be hosting multiple tiles based applications on the same servlet container, you will be tempted to place thestruts.jar
file into the shared repository supported by your container. Be advised that this will likely cause you to encounter ClassNotFoundException problems unless all of your application classes are stored in the shared repository. - lib/struts1.0/tilesForStruts1.0.jar - Same as before, but for use with Struts1.0.x.
-
lib/tiles.tld - These is the "tag library
descriptor" file that describe the custom tags in the Tiles tag
libraries. It should be copied into the
WEB-INF
directory of your web application. - webapps/tiles-doc.war or webapps/struts-tiles.war - This is a "web application archive" file containing all of the Tiles documentation found on the Tiles web site (including these pages). You can install this web application on any servlet container compatible with Servlet API 2.2 or later.
- webapps/tiles-channel.war - Examples using a custom definition factory.
- webapps/tiles-blank.war - 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.
- webapps/tiles-blank-struts1.1.war - A blank application to use with Struts1.1
- webapps/tiles-blank-struts1.0.war - A blank application to use with Struts1.0.x
To use Tiles in your own application, you will need to follow these steps:
- Copy the files
lib/commons-*.jar
into theWEB-INF/lib
directory of your web application. - Copy the file
lib/tiles.jar
from the Tiles distribution into theWEB-INF/lib
directory of your web application. - Copy all of the files that match
lib/*.tld
from the Tiles distribution into theWEB-INF
directory of your web application. - If you want to use definitions configuration file, you
need to initialize the definitions factory. This can be done as follows:
- Modify the
WEB-INF/web.xml
file for your web application to use a<servlet>
that initializes the factory and catch Struts action forwards to check for definition name. Use theWEB-INF/web.xml
file from the Tiles example application for a detailed example of the required syntax.<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> ...
- If you don't want to use Struts, use
org.apache.struts.tiles.TilesServlet
as servlet. - Create a configuration file for definitions. Its name must
match the one provided before in
WEB-INF/web.xml
. Several comma separated names can be provided.
- Modify the
- Modify the
WEB-INF/web.xml
file of your web application to include the following tag library declarations:
<taglib> <taglib-uri>/WEB-INF/tiles.tld</taglib-uri> <taglib-location>/WEB-INF/tiles.tld</taglib-location> </taglib>
- 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:
<%@ taglib uri="/WEB-INF/tiles.tld" prefix="tiles" %>
- When compiling the Java classes that comprise your application,
be sure to include the
tiles.jar
andcommons-*.jar
files (copied earlier) on the CLASSPATH that is submitted to the compiler.
Note to Struts 1.0 users :
- You should use a
tiles.jar
build with Struts1.0.x. - If you have downloaded a Tiles version build with Struts1.0.x, you already have it.
- Consider to use tilesForStruts1.0.jar located in
lib/struts1.0
Note to Struts1.1 users :
- You should also initialize a
TilesRequestProcessor
. - To do so, add following lines in your
struts-config.xml
file :<controller processorClass="org.apache.struts.tiles.TilesRequestProcessor"> </controller>
Installing Tiles with your servlet container
WARNING - Do NOT add
tiles.jar
to the classpath of your servlet container in
an attempt to avoid placing it in the /WEB-INF/lib
directory of each individual web app! Doing so will cause problems with
ClassNotFoundException
exceptions.
For most containers, you need only to:
- Copy the WAR files in your Tiles
/webapp
directory to your containerswebapps
directory. - In some cases, you may need to restart your container if it is running.
Status of various containers
For status of additional containers, please refer to the Struts installation page).
Building Tiles From Source
First, download a source distribution of Tiles from here or from Struts contrib directory. Then, make sure you have downloaded and installed all of the prerequisite software packages described above. You also need the appropriate struts version (1.0.x or 1.1)
To build Tiles, you will need to customize the build process to the details of your development environment as follows:
- The Tiles source distribution uses a file named
build.properties
(in the top-level directory of the distribution) to identify the location of external components that Tiles depends on. - There is no
build.properties
file included with the source distribution. However, there is an example file namedbuild.properties.example
that you can copy tobuild.properties
and then customize. - The properties you must configure in
build.properties
are documented inbuild.properties.example
- Tiles build require a Struts library. You can use either a
Struts1.0.x or 1.1
struts.jar
. The resultingtiles.jar
will run with the usedstruts.jar
. You specify the Struts home withstruts.home
property.
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
build.properties
file as described above. Then, type:
ant dist
This command will create a binary distribution of Tiles, in a
directory named dist
(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 preceding section.
IMPORTANT NOTE: The tiles.jar
, as well as the JAR
files from the Jakarta Commons project, must be in your classpath
when compiling Tiles. The build.xml
provided does this
automatically. If you use your development machine to test Tiles
application locally, be sure that the tiles.jar
is
NOT on your classpath when your container is
running.