$Id: README,v 1.2 2001/08/06 20:42:03 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 . Another JAXP-compatible parser that has been reported to work fine with Struts is Xerces, version 1.3.1, available at . 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 . - (*) Download and unpack a Struts binary distribution, available from . - (*) 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 element to define the controller servlet, and a 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: /WEB-INF/tiles.tld /WEB-INF/tiles.tld - (*) 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 . 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.