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            &lt;-- Unix platform
          build dist                 &lt;-- 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>&lt;servlet&gt;</code> element to define the
          controller servlet, and a <code>&lt;servlet-mapping&gt;</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>
          &lt;taglib&gt;
            &lt;taglib-uri&gt;/WEB-INF/struts.tld&lt;/taglib-uri&gt;
            &lt;taglib-location&gt;/WEB-INF/struts.tld&lt;/taglib-location&gt;
          &lt;/taglib&gt;
          </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>
          &lt;@ taglib uri="/WEB-INF/struts.tld" prefix="struts" %&gt;
          </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 &#169; 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>