You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@struts.apache.org by cr...@locus.apache.org on 2000/08/28 04:14:38 UTC
cvs commit: jakarta-struts/web/documentation index.jsp
craigmcc 00/08/27 19:14:38
Modified: . build.xml
Added: src/doc index.xml installation.xml project.xml
src/doc/images jakarta-logo.gif struts-power.gif struts.gif
src/doc/stylesheets struts.xsl
Removed: web/documentation index.jsp
Log:
Update the struts-documentation application to a vastly improved look
and feel, based on generating the pages using a Xalan-powered XSLT
transformation. Most of the original content still needs to be converted,
but this commit provides the framework.
The Struts documentation will also be uploaded and used as the contents
of the Struts project web site at <http://jakarta.apache.org/struts>.
Revision Changes Path
1.10 +15 -1 jakarta-struts/build.xml
Index: build.xml
===================================================================
RCS file: /home/cvs/jakarta-struts/build.xml,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- build.xml 2000/07/26 05:49:14 1.9
+++ build.xml 2000/08/28 02:14:36 1.10
@@ -58,17 +58,31 @@
<!-- BUILD: Compile documentation application components -->
<target name="compile.documentation"
depends="compile.library,prepare.documentation">
+
+ <!-- Compile beans and tags required by the documentation app -->
<!--
<javac srcdir="src/documentation"
destdir="${build.home}/documentation/WEB-INF/classes"
classpath="${build.home}/library/classes:${servlet.jar}"
debug="true" optimize="false" deprecation="false"/>
-->
- <copydir src="web/documentation" dest="${build.home}/documentation"/>
+
+ <!-- Copy Struts JAR file and TLD to the documentation app -->
<copyfile src="${dist.home}/lib/${app.name}.jar"
dest="${build.home}/documentation/WEB-INF/lib/${app.name}.jar"/>
<copyfile src="${dist.home}/lib/${app.name}.tld"
dest="${build.home}/documentation/WEB-INF/${app.name}.tld"/>
+
+ <!-- Copy static documentation content -->
+ <copyfile src="TODO" dest="${build.home}/documentation/todo.txt"/>
+ <copydir src="web/documentation" dest="${build.home}/documentation"/>
+
+ <!-- Create dynamically generated documentation -->
+ <style basedir="src/doc" destdir="${build.home}/documentation"
+ extension=".html" style="stylesheets/struts.xsl" includes="*.xml"/>
+ <copydir src="src/doc" dest="${build.home}/documentation"
+ includes="**/*.css,**/*.gif,**/*.html,**/*.jpg,**/*.js"/>
+
</target>
<!-- BUILD: Compile example application components -->
1.1 jakarta-struts/src/doc/index.xml
Index: index.xml
===================================================================
<?xml version="1.0"?>
<document url="./index.xml">
<properties>
<author>Craig R. McClanahan</author>
<title>The Struts Framework Project</title>
</properties>
<body>
<section name="Welcome to Struts">
<a name="Welcome"></a>
<p>Welcome to the Struts Framework! The goal of this project
is to provide an open source framework useful in building web applications
with Java <a href="http://java.sun.com/products/servlet">Servlet</a> and
<a href="http://java.sun.com/products/jsp">JavaServer Pages</a> (JSP)
technology. Struts encourages appliation architectures based on the
Model-View-Controller (MVC) design paradigm, colloquially known as
<i>Model 2</i> in discussions on various servlet and JSP related
mailing lists.</p>
<p>Struts includes the following primary areas of functionality:</p>
<ul>
<li>A controller servlet that dispatches requests to appropriate
<strong>Action</strong> classes provided by the application
developer.</li>
<li>JSP custom tag libraries, and associated support in the controller
servlet, that assists developers in creating interactive form-based
applications.</li>
<li>Utility classes to support XML parsing, automatic population of
JavaBeans properties based on the Java reflection APIs, and
internationalization of prompts and messages.</li>
</ul>
<p>Struts is part of the <a href="http://jakarta.apache.org">Jakarta
Project</a>, sponsored by the
<a href="http://www.apache.org">Apache Software Foundation</a>. The
official Struts home page is at
<a href="http://jakarta.apache.org/struts">http://jakarta.apache.org/struts</a>.
</p>
</section>
<section name="Acquiring Struts">
<a name="Acquiring"></a>
<p>You can acquire binary and source distributions of Struts from the
following locations:</p>
<ul>
<li>Download the source directly via
<a href="http://jakarta.apache.org/getinvolved/cvsindex.html">
Anonymous CVS</a>.</li>
<li>Download nightly binary distributions from
<a href="http://jakarta.apache.org/builds/jakarta-struts/nightly">
here</a>.</li>
<li>Download nightly source distributions from
<a href="http://jakarta.apache.org/builds/jakarta-struts/nightly/src">
here</a>.</li>
</ul>
<p>In addition to the Struts distribution, you will need to ensure that
you have downloaded and installed all of the
<a href="installation.html#Prerequisites">prerequisite</a> software
applications. Then, follow the appropriate instructions to
<a href="installation.html#Building">build Struts from the source
distribution</a>, or <a href="@installation.html#Installing">install and
use a Struts binary distribution</a> in your web application.</p>
</section>
<section name="Getting Involved">
<p>There are a number of ways to get more involved in the Struts
community, including contributing to the future development of Struts.
Check out the following resources:</p>
<ul>
<li><strong>STRUTS-USER Mailing List</strong> - Subscribe to the
<a href="mailto:struts-user-subscribe@jakarta.apache.org">STRUTS-USER</a>
mailing list to communicate with other developers that are using
Struts for their own applications, including questions about the
installation of Struts, and the usage of particular Struts features.</li>
<li><strong>STRUTS-DEV Mailing List</strong> - Subscribe to the
<a href="mailto:struts-dev-subscribe@jakarta.apache.org">STRUTS-DEV</a>
mailing list to communicate with other developers interested in expanding
and improving the functionality supported by Struts itself.</li>
<li><strong>Patches and Modules</strong> - You can contribute patches and
new modules to Struts by posting them to the STRUTS-DEV mailing list.
After discussion and acceptance, one of the existing Committers will
add your contribution to the Struts source code base (with credit to
you, of course).</li>
<li><strong>Become A Committer</strong> - If you wish to contribute directly
to the development of Struts, and have commit access to the CVS source
repository, you can be nominated (or nominate yourself) for Committer
status on this project. The rules by which committers are voted on are
listed at the
<a href="http://jakarta.apache.org/guidelines/index.html">Jakarta
web site</a>.</li>
</ul>
</section>
</body>
</document>
1.1 jakarta-struts/src/doc/installation.xml
Index: installation.xml
===================================================================
<?xml version="1.0"?>
<document url="./index.xml">
<properties>
<author>Craig R. McClanahan</author>
<title>The Struts Framework Project - Installation</title>
</properties>
<body>
<section name="Prerequisite Software">
<a name="Prerequisites"></a>
<p>In order to build a Struts source distribution, or install and use a
Struts binary distribution, you will need to acquire and install several
other software packages, as follows:</p>
<ul>
<li><strong>Java Development Kit</strong> - You must download and install
a version 1.1 (or later) Java Development Kit implementation for your
operating system platform. You <em>must</em> have a Java2 version
(JDK 1.2 or later) to build the Struts source distribution, and several
of the custom tags in the Struts library require Java2 to execute.
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 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
<a href="http://jakarta.apache.org/tomcat">Tomcat</a> (version 3.1
or later required, version 3.2 or later recommended).</li>
<li><strong>Ant Build System</strong> - If you are building Struts from the
source distribution, you must download and install version 1.1 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 Struts.</li>
<li><strong>Servlet API Classes</strong> - In order to compile Struts itself,
or applications that use Struts, 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>XML Parser</strong> - Struts requires the presence of an XML
parser that is compatible with the Java API for XML Parsing (JAXP)
specification. You can download and install the JAXP
<a href="http://java.sun.com/xml">reference implementation</a>,
which is required for building the Struts source distribution. In
Struts-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>
Struts, below.</li>
<li><strong>Xalan XSLT Processor</strong> - If you are building Struts from
the source distribution, you must download and install version 1_2_D01
(or later) of the <a href="http://xml.apache.org/xalan">Xalan</a>
XSLT processor (which also includes the Xerces XML parser). This
processor is used to convert the Struts documentation from its internal
XML-based format into the HTML that is presented in the Struts
documentation application.</li>
</ul>
</section>
<section name="Building Struts From Source">
<a name="Building"></a>
<p>First, download a source distribution of Struts by following the
instructions <a href="index.html#Acquiring">here</a>. Then, make sure
you have downloaded and installed all of the
<a href="#Prerequisites">prerequisite</a> software packages described
above.</p>
<p>To build Struts, you will need to customize your development
environment as follows:</p>
<ul>
<li>Set an environment variable <code>ANT_HOME</code> that contains the
absolute pathname of the directory where you installed Ant.</li>
<li>Set an environment variable <code>JAVA_HOME</code> that contains the
absolute pathname of the directory where you installed your
Java Development Kit.</li>
<li>Set an environment variable <code>SERVLETAPI_HOME</code> that contains
the absolute pathname of the directory where you installed the Servlet
API distribution (not required if you have <code>servlet.jar</code>
on your CLASSPATH already).</li>
</ul>
<p>To build a "distribution" version of Struts, first change your current
directory to the directory in which you have unpacked the Struts
source distribution, and then type one of the following commands (based
on whether you are running on a Unix or Windows platform):</p>
<pre>
./build.sh dist <-- Unix platform
build dist <-- Windows platform
</pre>
<p>This command will create a binary distribution of Struts, in a
directory named <code>../dist/struts</code> (relative to where you
are compiling from). This directory contains an exact replica of the
files included in a binary distribution of Struts.</p>
</section>
<section name="Install A Struts Binary Distribution">
<a name="Installing"></a>
<p>First, download a binary distribution of Struts by following the
instructions <a href="index.html#Acquiring">here</a>. Then, make sure
you have downloaded and installed all of the
<a href="#Prerequisites">prerequisite</a> software packages described
above.</p>
<p>Unpack the Struts binary distribution into a convenient directory.
(If you build Struts 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:</p>
<ul>
<li><strong>lib/struts.jar</strong> - This JAR file contains all of the
Java classes included in Struts. It should be copied into the
<code>WEB-INF/lib</code> directory of your web application.</li>
<li><strong>lib/struts.tld</strong> - This is the "tag library descriptor"
file that describes the custom tags in the Struts library. It should
be copied into the <code>WEB-INF</code> directory of your web
application.</li>
<li><strong>webapps/struts-documentation.war</strong> - This is a
"web application archive" file containing all of the Struts
documentation found on the
<a href="http://jakarta.apache.org/struts">Struts 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/struts-example.war</strong> - This is an example
web application that uses a large percentage of Struts features.
You can install this web application on any servlet container
compatible with the Servlet 2.2 (or later) and JSP 1.1 (or later)
specifications.</li>
</ul>
<p>To use Struts in your own application, you will need to follow
these steps:</p>
<ul>
<li>Copy the file <code>lib/struts.jar</code> from the Struts distribution
into the <code>WEB-INF/lib</code> directory of your web application.
</li>
<li>Copy the file <code>lib/struts.tld</code> from the Struts distribution
into the <code>WEB-INF</code> directory of your web application.</li>
<li>Modify the <code>WEB-INF/web.xml</code> file for your web application
to include a <code><servlet></code> element to define the
controller servlet, and a <code><servlet-mapping></code> element
to establish which request URIs are mapped to this servlet. Use the
<code>WEB-INF/web.xml</code> file from the Struts example application
for a detailed example of the required syntax.</li>
<li>Modify the <code>WEB-INF/web.xml</code> file of your web application
to include the following tag library declaration:
<pre>
<taglib>
<taglib-uri>/WEB-INF/struts.tld</taglib-uri>
<taglib-location>/WEB-INF/struts.tld</taglib-location>
</taglib>
</pre>
</li>
<li>Create a file <code>WEB-INF/action.xml</code> that defines the action
mappings for your specific application. You can use the
<code>action.xml</code> file from the Struts example application
for a detailed example of the required syntax.</li>
<li>At the top of each JSP page that will use the Struts custom tags,
add a line declaring the Struts custom tag library, like this:
<pre>
<@ taglib uri="/WEB-INF/struts.tld" prefix="struts" %>
</pre>
</li>
<li>When compiling the Java classes that comprise your application, be sure
to include the <code>struts.jar</code> file (copied earlier) on the
CLASSPATH that is submitted to the compiler.</li>
</ul>
</section>
</body>
</document>
1.1 jakarta-struts/src/doc/project.xml
Index: project.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<project name="Struts Framework"
href="http://jakarta.apache.org/struts"
image="images/struts.gif">
<title>Struts Framework</title>
<menu name="Overview">
<item name="Home" href="index.html"/>
<item name="Installation" href="installation.html"/>
<item name="TODO" href="todo.txt"/>
</menu>
<menu name="Old Documents">
<item name="User's Guide" href="users_guide.html"/>
<item name="Tag Library (Old)" href="tags.html"/>
<item name="API Javadoc" href="api/index.html"/>
</menu>
<!--
<menu name="New Documents">
<item name="Bean Tags" href="tags-bean.html"/>
<item name="Form Tags" href="tags-form.html"/>
<item name="Logic Tags" href="tags-logic.html"/>
<item name="Message Tags" href="tags-message.html"/>
<item name="Template Tags" href="tags-template.html"/>
</menu>
-->
</project>
1.1 jakarta-struts/src/doc/images/jakarta-logo.gif
<<Binary file>>
1.1 jakarta-struts/src/doc/images/struts-power.gif
<<Binary file>>
1.1 jakarta-struts/src/doc/images/struts.gif
<<Binary file>>
1.1 jakarta-struts/src/doc/stylesheets/struts.xsl
Index: struts.xsl
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<!-- Content Stylesheet for Struts Documentation -->
<!-- $Id: struts.xsl,v 1.1 2000/08/28 02:14:38 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="color-bg" select="'#ffffff'"/>
<xsl:variable name="color-fg" select="'#000000'"/>
<xsl:variable name="color-link" select="'#023264'"/>
<xsl:variable name="color-text" select="'#000000'"/>
<xsl:variable name="section-bg" select="'#023264'"/>
<xsl:variable name="section-fg" select="'#ffffff'"/>
<!-- Match the entire document and process to a web page -->
<xsl:template match="/">
<xsl:variable name="project" select="document('../project.xml')/project"/>
<html>
<head>
<meta name="author" content="{document/properties/author/.}"/>
<!-- <link rel="stylesheet" type="text/css" href="default.css"/> -->
<xsl:choose>
<xsl:when test="/document/properties/title">
<title><xsl:value-of select="/document/properties/title"/></title>
</xsl:when>
<xsl:when test="/document/body/title">
<title><xsl:value-of select="/document/body/title"/></title>
</xsl:when>
<xsl:otherwise>
<title><xsl:value-of select="$project/title"/></title>
</xsl:otherwise>
</xsl:choose>
</head>
<body bgcolor="{$color-bg}" link="{$color-link}" vlink="{$color-link}"
alink="{$color-link}" text="{$color-text}">
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr><td colspan="2">
<a href="http://jakarta.apache.org">
<img src="images/jakarta-logo.gif" align="left" border="0"/>
</a>
<img src="images/struts.gif" align="right" border="0"/>
</td></tr>
<tr><td colspan="2">
<hr/>
</td></tr>
<tr><td width="120" valign="top" cellspacing="2" cellpadding="0">
<table border="0" cellspacing="2">
<xsl:for-each select="$project/menu">
<tr><td align="left" colspan="2">
<font color="${color-link}"><b>
<xsl:value-of select="@name"/>
</b></font>
</td></tr>
<xsl:for-each select="item">
<tr>
<td width="20">*</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:for-each>
</xsl:for-each>
</table>
</td>
<td width="480" cellspacing="2" cellpadding="0" valign="top">
<xsl:apply-templates select="document/body"/>
</td></tr>
<tr><td colspan="2">
<hr/>
</td></tr>
<tr><td colspan="2">
<div align="center"><font size="-1">
Copyright © 2000, Apache Software Foundation
</font></div>
<img src="images/struts-power.gif" align="right" border="0"/>
</td></tr>
</table>
</body>
</html>
</xsl:template>
<!-- Process the document body -->
<xsl:template match="document/body">
<table border="0" width="100%">
<xsl:for-each select="section">
<tr><td bgcolor="{$section-bg}" cellspacing="5" cellpadding="5">
<font color="{$section-fg}" face="arial,helvetica,sanserif" size="+1"><b>
<xsl:value-of select="@name"/>
</b></font>
</td></tr>
<tr><td cellspacing="0" cellpadding="0">
<blockquote>
<xsl:apply-templates/>
</blockquote>
</td></tr>
</xsl:for-each>
</table>
</xsl:template>
<!-- Process an individual paragraph -->
<xsl:template match="p">
<p><xsl:apply-templates/><br/></p>
</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>