$Id: README,v 1.2 2001/08/07 23:03:44 cedric Exp $

				Tiles
				======

File Copyrighted Struts				
				
Introduction
------------

This subproject contains the source code for the "Tiles" application support
package.




Installing and Using Tiles
---------------------------

You can utilize a binary distribution of Tiles in your own web applications
by following these steps.  All of these steps are required if you want to
run the Tiles application framework (including executing the example
application).  If you simply wish to use the Tiles custom tag library,
and not the MVC framework, only the steps marked (*) are required.

- (*) Download and install a Java2 (version 1.2 or later) Java Development Kit
  Kit implementation for your operating system platform.  Define an environment
  variable JAVA_HOME that points at the base directory of your JDK
  installation, and add the directory "$JAVA_HOME/bin" to your PATH variable.

- Download and install an XML parser that is compatible with the Java
  API for XML Parsing (JAXP) specification.  A useful XML parser is the
  JAXP Reference Implementation, version 1.1 or later, that is available
  at <http://java.sun.com/xml>.  Another JAXP-compatible parser that has
  been reported to work fine with Struts is Xerces, version 1.3.1,
  available at <http://xml.apache.org>.  Be sure to add the "jaxp.jar" and
  "crimson.jar" (or whatever JAR file comes with your parser) files to
  your CLASSPATH environment variable.

- (*) Download and install a servlet container that supports the Servlet
  API Specification, version 2.2 or later, and the JavaServer Pages (JSP)
  Specification, version 1.1 or later.  A useful servlet container is
  Tomcat, version 3.2 or later, that is available at
  <http://jakarta.apache.org>.

- (*) Download and unpack a Struts binary distribution, available from
  <http://jakarta.apache.org/builds/jakarta-struts/nightly/>.

- (*) Install the Tiles documentation application by deploying file
  "lib/tiles-doc.war" into your servlet container, using the
  standard techniques supported by that container.  (For Tomcat, simply
  copy this file to the $TOMCAT_HOME/webapps directory and restart Tomcat).

- Install the Tiles tutorial application by deploying file
  "lib/tiles-tutorial.war" into your servlet container, using the standard
  techniques supported by that container.  (For Tomcat, simply copy this
  file to the $TOMCAT_HOME/webapps directory and restart Tomcat).

- (*) Copy the files "lib/tiles.tld" from the Tiles distribution into the
  "WEB-INF" directory of your web application.

- (*) Copy the JAR files from the "lib" directory of the Tiles distribution
  (such as "tiles.jar" and "commons-*.jar") into the "WEB-INF/lib" directory
  of your web application.

- (*) Modify your "WEB-INF/web.xml" file to include a <servlet> element to
  define the controller servlet, and a <servlet-mapping> element to establish
  which request URIs are mapped to this servlet.  Normally, you will map
  the controller servlet to a wildcard pattern ("/execute/*") or a filename
  extension pattern ("*.do").  Use the "WEB-INF/web.xml" file from the
  example application (see below) for an example of how this is done.

- (*) Modify the "WEB-INF/web.xml" file for your web application to include
  a tag library declaration like this for each Tiles tag library you will
  be using:

	<taglib>
	    <taglib-uri>/WEB-INF/tiles.tld</taglib-uri>
	    <taglib-location>/WEB-INF/tiles.tld</taglib-location>
	</taglib>

- (*) In each JSP page that will use the Tiles custom tags, add a line at
  the top of the page like this (for each Struts tag library needed):

	<%@ taglib uri="/WEB-INF/tiles.tld" prefix="tiles" %>

  (If you wish, you can use a prefix other that "tiles").

- When compiling your web application components, be sure that the
  JAR files (copied above) are included on the CLASSPATH environment
  variable used by your Java compiler.


The Tiles Documentation and Tutorial Application
------------------------------------------------

Tiles comes with a web application that contains all of the documentation
relevant to an application developer who wants to use it, including:
* Reference manual for the custom tag library
* API documentation for the Tiles classes

To view this documentation, deploy the file "webapps/tiles-doc.war"
into your servlet container, and use a web browser to access a URL like this:

	http://localhost:8080/tiles-doc

This application also contains dynamic examples from the tutorial. You can 
browse them from the URL :

	http://localhost:8080/tiles-doc/tutorial


For notes about installing Tiles applications on various servlet containers,
please see the INSTALL document in the same directory as this README file.



Using the Struts Source Distribution
------------------------------------

If you wish to contribute to the development of the Struts and Tiles toolkit, you should
download and install a source distribution of Tiles from
<http://jakarta.apache.org/builds/jakarta-struts/nightly/src>.  You will also
need a recent nightly build of the Ant project development tool (you *must*
use version 1.3 or later of Ant).

Before committing any changes to the Struts CVS repository, you must do a
"build clean" followed by a "build dist", to ensure that everything compiles
and builds cleanly.
