craigmcc 2002/07/05 18:36:04
Modified: . build-webapps.xml
Added: doc/stylesheets tiles.xsl
doc/tiles installation.xml
Log:
Beginnings of generating the Tiles documentation that is done via XSLT.
Revision Changes Path
1.14 +5 -0 jakarta-struts/build-webapps.xml
Index: build-webapps.xml
===================================================================
RCS file: /home/cvs/jakarta-struts/build-webapps.xml,v
retrieving revision 1.13
retrieving revision 1.14
diff -u -r1.13 -r1.14
--- build-webapps.xml 6 Jul 2002 01:13:46 -0000 1.13
+++ build-webapps.xml 6 Jul 2002 01:36:04 -0000 1.14
@@ -232,6 +232,11 @@
<include name="**/*.js"/>
</fileset>
</copy>
+ <!-- Create the Tiles documentation -->
+ <style basedir="${doc.dir}/tiles"
+ destdir="${build.home}/tiles-documentation"
+ extension=".html" style="${doc.dir}/stylesheets/tiles.xsl"
+ includes="*.xml"/>
<!-- Compile Tiles contrib -->
<!--
1.1 jakarta-struts/doc/stylesheets/tiles.xsl
Index: tiles.xsl
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<!-- Content Stylesheet for Struts Documentation -->
<!-- $Id: tiles.xsl,v 1.1 2002/07/06 01:36:04 craigmcc Exp $ -->
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform";
version="1.0">
<!-- Output method -->
<xsl:output method="html" indent="no"/>
<!-- Defined variables -->
<xsl:variable name="body-bg" select="'#ffffff'"/>
<xsl:variable name="body-fg" select="'#000000'"/>
<xsl:variable name="body-link" select="'#023264'"/>
<xsl:variable name="banner-bg" select="'#023264'"/>
<xsl:variable name="banner-fg" select="'#ffffff'"/>
<!-- Process an entire document into an HTML page -->
<xsl:template match="document">
<xsl:variable name="project"
select="document('../project.xml')/project"/>
<table border="0" width="100%" cellspacing="5">
<tr>
<td valign="top">
<xsl:apply-templates select="body"/>
</td>
</tr>
</table>
</xsl:template>
<!-- Process a menu for the navigation bar -->
<xsl:template match="menu">
<table border="0" cellspacing="5">
<tr>
<th colspan="2" align="left">
<font color="{body-link}"><strong>
<xsl:value-of select="@name"/>
</strong></font>
</th>
</tr>
<xsl:apply-templates/>
</table>
</xsl:template>
<!-- Process a menu item for the navigation bar -->
<xsl:template match="item">
<tr>
<td align="center" width="15"></td>
<td>
<font size="-1">
<xsl:variable name="href">
<xsl:value-of select="@href"/>
</xsl:variable>
<a href="{$href}"><xsl:value-of select="@name"/></a>
</font>
</td>
</tr>
</xsl:template>
<!-- Process a documentation section -->
<xsl:template match="section">
<xsl:choose>
<xsl:when test="@href">
<xsl:variable name="href">
<xsl:value-of select="@href"/>
</xsl:variable>
<a name="{$href}"></a>
</xsl:when>
</xsl:choose>
<table border="0" cellspacing="5" cellpadding="5" width="100%">
<tr><td bgcolor="{$banner-bg}">
<font color="{$banner-fg}" face="arial,helvetica,sanserif" size="+1">
<strong><xsl:value-of select="@name"/></strong>
</font>
</td></tr>
<tr><td>
<blockquote>
<xsl:apply-templates/>
</blockquote>
</td></tr>
</table>
</xsl:template>
<!-- Process a tag library section -->
<xsl:template match="taglib">
<table border="0" cellspacing="5" cellpadding="5" width="100%">
<tr><td bgcolor="{$banner-bg}">
<font color="{$banner-fg}" face="arial,helvetica,sanserif" size="+1">
<strong><xsl:value-of select="display-name"/></strong>
</font>
</td></tr>
<tr><td>
<blockquote>
<xsl:apply-templates select="info"/>
</blockquote>
</td></tr>
<tr><td>
<blockquote>
<table border="1" cellspacing="2" cellpadding="2">
<tr>
<th width="15%">Tag Name</th>
<th>Description</th>
</tr>
<xsl:for-each select="tag">
<tr>
<td align="center">
<xsl:variable name="name">
<xsl:value-of select="name"/>
</xsl:variable>
<a href="#{$name}"><xsl:value-of select="name"/></a>
</td>
<td>
<xsl:value-of select="summary"/>
</td>
</tr>
</xsl:for-each>
</table>
</blockquote>
</td></tr>
</table>
<xsl:apply-templates select="tag"/>
</xsl:template>
<!-- Process an individual tag -->
<xsl:template match="tag">
<xsl:variable name="name">
<xsl:value-of select="name"/>
</xsl:variable>
<a name="{$name}"></a>
<table border="0" cellspacing="2" cellpadding="2">
<tr><td bgcolor="{$banner-bg}">
<font color="{$banner-fg}" face="arial,helvetica,sanserif">
<strong><xsl:value-of select="name"/></strong> -
<xsl:value-of select="summary"/>
</font>
</td></tr>
<tr><td>
<blockquote>
<xsl:apply-templates select="info"/>
</blockquote>
</td></tr>
<tr><td>
<blockquote>
<table border="1" cellspacing="2" cellpadding="2">
<tr>
<th width="15%">Attribute Name</th>
<th>Description</th>
</tr>
<xsl:for-each select="attribute">
<tr>
<td align="center">
<xsl:value-of select="name"/>
</td>
<td>
<xsl:apply-templates select="info"/>
<xsl:variable name="required">
<xsl:value-of select="required"/>
</xsl:variable>
<xsl:if test="required='true'">
[Required]
</xsl:if>
<xsl:if test="rtexprvalue='true'">
[RT Expr]
</xsl:if>
</td>
</tr>
</xsl:for-each>
</table>
</blockquote>
</td></tr>
</table>
</xsl:template>
<!-- Process an individual paragraph -->
<xsl:template match="p">
<p><xsl:apply-templates/><br/></p>
</xsl:template>
<!-- Process a task list section -->
<xsl:template match="task-list">
<xsl:choose>
<xsl:when test="@href">
<xsl:variable name="href">
<xsl:value-of select="@href"/>
</xsl:variable>
<a name="{$href}"></a>
</xsl:when>
</xsl:choose>
<table border="0" cellspacing="5" cellpadding="5" width="100%">
<tr><td bgcolor="{$banner-bg}">
<font color="{$banner-fg}" face="arial,helvetica,sanserif" size="+1">
<xsl:value-of select="@name"/>
</font>
</td></tr>
<tr><td>
<xsl:apply-templates select="info"/>
</td></tr>
<tr><td>
<blockquote>
<table border="1" cellspacing="5" cellpadding="5" width="100%">
<tr>
<th width="75%">Description</th>
<th width="25%">Volunteer</th>
</tr>
<xsl:apply-templates select="task"/>
</table>
</blockquote>
</td></tr>
</table>
</xsl:template>
<!-- Process an individual task (in a TODO list) -->
<xsl:template match="task">
<tr>
<td>
<xsl:choose>
<xsl:when test="@name">
<em><xsl:value-of select="@name"/></em>.
</xsl:when>
</xsl:choose>
<xsl:value-of select="info"/>
</td>
<td><xsl:value-of select="assigned"/></td>
</tr>
</xsl:template>
<!-- Process everything else by just passing it through -->
<xsl:template match="*|@*">
<xsl:copy>
<xsl:apply-templates select="@*|*|text()"/>
</xsl:copy>
</xsl:template>
</xsl:stylesheet>
1.1 jakarta-struts/doc/tiles/installation.xml
Index: installation.xml
===================================================================
<!-- <?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">
<p></p>
<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</li>
<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>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 <b>must</b> 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 <b>must</b> 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>
</li>
(version 3.1 or later required, version 3.2 or later recommended).
<li><strong>XML Parser</strong> - Tiles <b>requires</b> 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.
</li>
<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><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:
</li>
<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><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 like 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. This example has some b
</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 <i>definitions configuration file</i>, you need
to
initialize the definitions factory. This can be done as follow :
</li>
<ul>
<li>Modify the <code>WEB-INF/web.xml</code> file for your web
application
to use a <code><servlet></code> that initialize 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.
</li>
<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>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>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 Struts1.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 :
</li>
<pre>
<controller processorClass="org.apache.struts.tiles.TilesRequestProcessor">
</controller>
</pre>
</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>
<h3>Status of various containers</h3>
<p>For status of additional containers, please refer to the
<a href="http://jakarta.apache.org/struts/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
<b>all</b> 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>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
