jakarta-taglibs-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From craig...@locus.apache.org
Subject cvs commit: jakarta-taglibs/doc binarydist.html index.html sourcedist.html
Date Mon, 10 Apr 2000 00:52:11 GMT
craigmcc    00/04/09 17:52:11

  Added:       doc      binarydist.html index.html sourcedist.html
  Log:
  Initial crack at documentation for the proposed layout of the
  JAKARTA-TAGLIBS project directory, including procedures for addding
  new custom tag libraries and using them in your applications.
  
  Revision  Changes    Path
  1.1                  jakarta-taglibs/doc/binarydist.html
  
  Index: binarydist.html
  ===================================================================
  <html>
  <head>
  <title>Using the JAKARTA-TAGLIBS Binary Distribution</title>
  </head>
  <body bgcolor="white">
  
  <h1>Using the JAKARTA-TAGLIBS Binary Distribution</h1>
  
  <h2>Download and Installation</h2>
  
  <p>Binary downloads of the JAKARTA-TAGLIBS distribution, as with all other
  Jakarta projects, are available from the Jakarta web site, at
  <a href="http://jakarta.apache.org/downloads/binindex.html">http://jakarta.apache.org/downloads/binindex.html</a>.
  Download and unpack the distribution archive into a convenient subdirectory.
  
  <h2>Distribution Directory Structure</h2>
  
  <p>The distribution archive will contain the following file and directory
  structure:
  
  <ul>
  <li><b>LICENSE</b> - A copy of the Apache Software Foundation
      license under which all Jakarta project software is distributed.
  <li><b>README</b> - A brief README file that contains pointers
      to the documentation that is available.
  <li><b>doc</b> - A directory containing documentation about the
      JAKARTA-TAGLIBS project as a whole, including this file.  The following
      documents are included:
      <ul>
      <li><a href="index.html">Documentation Index</a>
      <li><a href="binarydist.html">Using the JAKARTA-TAGLIBS Binary
          Distribution</a> (this document)
      <li><a href="sourcedist.html">Using the JAKARTA-TAGLIBS Source
          Distribution</a>
      </ul>
  <li>A directory for each custom tag library included in the JAKARTA-TAGLIBS
      project, where the directory name matches the short name of that project.
      Each directory will contain the following files, where
      <code>{library}</code> represents that project's short name:
      <ul>
      <li><b>{library}.tld</b> - The <i>tag library descriptor</i>
file for
          this custom tag library.  This file will normally be copied to the
          <code>/WEB-INF</code> subdirectory within your web application, and
          referenced with a <code>&lt;taglib&gt;</code> element in the
web
          application deployment descriptor (<code>/WEB-INF/web.xml</code>) file.
      <li><b>{library}.jar</b> - A JAR file containing the Java classes
and
          associated resources that comprise this custom tag library.  This file
          will normally be copied to the <code>/WEB-INF/lib</code> subdirectory
          within your web application, which makes these classes automatically
          visible within your application.
      <li><b>{library}-doc.war</b> - A web application containing developer
          documentation describing how to use the tags in this custom tag library
          in your own application.  This web application can be deployed and
          executed on any servlet container that is compatible with the Servlet
          API Specification, version 2.2 or later.
      <li><b>{library}-examples.war</b> - A web application containing one
or
          more examples that illustrate the use of this custom tag library.
          This web application can be deployed and executed on any servlet
          container that is compatible with the Servlet API Specification,
          version 2.2 or later.
      </ul>
  </ul>
  
  <h2>Using a Custom Tag Library in Your Application</h2>
  
  <p>To use one or more of the custom tag libraries included in JAKARTA-TAGLIBS
  in your own web applications, follow these steps:
  
  <ul>
  <li>Copy the <code>{library}.tld</code> file to the <code>/WEB-INF</code>
      subdirectory of your web application.
  <li>Copy the <code>{library}.jar</code> file to the <code>/WEB-INF/lib</code>
      subdirectory of your web application.
  <li>For each tag library you are going to use, add a
      <code>&lt;taglib&gt;</code> element to your web application deployment
      descriptor (<code>/WEB-INF/web.xml)</code>) file.  An example entry might
      look like this:
      <pre>
      &lt;taglib&gt;
  	&lt;taglib-uri&gt;http://jakarta.apache.org/taglibs/{library}&lt;/taglib-uri&gt;
  	&lt;taglib-location&gt;/WEB-INF/{library}.tld&lt;/taglib-location&gt;
      &lt;/taglib&gt;
      </pre>
  <li>At the top of each JSP page in your application that needs to use one or
      more tags from this custom tag library, add a
      <code>&lt;%@ taglib%gt;</code> directive identifying the URI of the
library
      you want to use (which must match the value you specified in the
      <code>&lt;taglib-uri&gt;</code> element in the web application deployment
      descriptor), and the tagname prefix you will use within this page to
      identify tags from this library.  An example entry might look like this:
      <pre>
      &lt;%@ taglib uri="http://jakarta.apache.org/taglibs/{library}" prefix="x" %&gt;
      </pre>
  <li>Whenever you wanted to use one of the tags from this library, you would
      simply include it, prefixed as you described in the <code>taglib</code>
      directive, and including attribute names and values as described in the
      documentation for this tag library.  For example, if the library you are
      using has a tag named <code>magic</code>, and you selected the "x"
      prefix as described above, you would might include this custom tag:
      <pre>
      &lt;x:magic/&gt;
      </pre>
      or, if this tag required attributes and perhaps some body text:
      <pre>
      &lt;x:magic id="beanName" name="xyz"&gt;
  	... Some body text and/or nested tags ...
      &lt;/x:magic&gt;
      </pre>
  <li>See the developer documentation provided with each custom tag library for
      detailed descriptions of the available tags within that library.
  </ul>
  
  <div align="center"><hr width="75%"><font size="2">
  $Id: binarydist.html,v 1.1 2000/04/10 00:52:10 craigmcc Exp $
  </font></div>
  
  </body>
  </html>
  
  
  
  1.1                  jakarta-taglibs/doc/index.html
  
  Index: index.html
  ===================================================================
  <html>
  <head>
  <title>JAKARTA-TAGLIBS Documentation Index</title>
  </head>
  <body bgcolor="white">
  <h1>JAKARTA-TAGLIBS Documentation Index</h1>
  
  <p>The following documents discuss downloading, installing, and using the
  JAKARTA-TAGLIBS distribution files:
  
  <ul>
  <li><a href="index.html">JAKARTA-TAGLIBS Documentation Index</a> -- This
file.
  <li><a href="binarydist.html">Using the JAKARTA-TAGLIBS Binary Distribution</a>
      -- If you wish to use one or more of the included custom tag libraries
      in your own web applications.
  <li><a href="sourcedist.html">Using the JAKARTA-TAGLIBS Source Distribution</a>
      -- If you wish to add your own custom tag library, modify the source code
      or documentation for an existing custom tag library, or you want to
      examine the source code to understand how custom tag libraries are
      constructed and used.
  </ul>
  
  <p>Each included custom tag library will contain its own documentation
  (packaged as a web application that can be run on any servlet container
  compatible with the Servlet API Specification, version 2.2 or later) and
  example application.  See the <a href="binarydist.html">binary distribution
  documentation</a> for more information.
  
  <h1>Included Custom Tag Libraries</h1>
  
  <p>The following custom tag libraries are included in the JAKARTA-TAGLIBS
  project, identified by their short name:
  
  <ul>
  <li><b>jspspec</b> - Example tags that are described in the JavaServer
Pages
      Specification, version 1.1.
  </ul>
  
  <div align="center"><hr width="75%"><font size="2">
  $Id: index.html,v 1.1 2000/04/10 00:52:10 craigmcc Exp $
  </font></div>
  
  </body>
  </html>
  
  
  
  1.1                  jakarta-taglibs/doc/sourcedist.html
  
  Index: sourcedist.html
  ===================================================================
  <html>
  <head>
  <title>Using the JAKARTA-TAGLIBS Source Distribution</title>
  </head>
  <body bgcolor="white">
  
  <h1>Using the JAKARTA-TAGLIBS Source Distribution</h1>
  
  
  <h2>Prerequisites</h2>
  
  <p>To successfully build the JAKARTA-TAGLIBS custom tag libraries, you must
  have successfully installed a <i>Java Development Kit</i> (JDK), version 1.1
or
  later, for your platform.  Your <code>PATH</code> environment variable must
  include the <code>/bin</code> directory of the JDK, such that the
  <code>java</code> and <code>javac</code> commands are executable.
  
  <p>Also, you must acquire and install a suitable <code>servlet.jar</code>
file
  that contains the standard servlet and JSP API classes for JSP version 1.1 or
  later.  Normally, this file will be included with your servlet container.  (If
  you have downloaded Tomcat, this file is available in the <code>lib</code>
  directory under your Tomcat installation home directory.  Set an environment
  variable named <code>SERVLET_JAR</code> to contain the absolute pathname to
  the location of this file, to make it visible when you build JAKARTA-TAGLIBS
  libraries.
  
  <p>To build the JAKARTA-TAGLIBS custom tag libraries, you will need the
  <code>Ant</code> development tool, which is used to control the build process.
  A binary distribution of Ant is available from
  <a href="http://jakarta.apache.org/downloads/binindex.html">http://jakarta.apache.org/downloads/binindex.html</a>.
  and should be unpacked (as described below) in a directory parallel to the
  directory into which you download and unpack the JAKARTA-TAGLIBS source
  distribution.
  
  <p>Finally, you will need a servlet container that is compatible with the
  Servlet API Specification, version 2.2 or later, and supports the JavaServer
  Pages (JSP) Specification, version 1.1 or later.  Many such servlet containers
  are available -- the Jakarta project hosts the Tomcat servlet container (which
  meets these requirements) at
  <a href="http://jakarta.apache.org/downloads/binindex.html">http://jakarta.apache.org/downloads/binindex.html</a>.
 (You can also download the source
  distribution of Tomcat and build it yourself, if you wish.)
  
  
  <h2>Download and Installation</h2>
  
  <p>Source downloads of the JAKARTA-TAGLIBS distribution, as with all other
  Jakarta projects, are available from the Jakarta web site at
  <a href="http://jakarta.apache.org/downloads/sourceindex.html">http://jakarta.apache.org/downloads/sourceindex.html</a>.
  
  <p>Download and unpack the JAKARTA-TAGLIBS distribution (from the link above)
  into a directory parallel to the directory into which you downloaded and
  unpacked the Ant distribution.  For example, you might end up with the
  following directory structure:
  
  <pre>
  your_home_directory/
      jakarta-ant/                <-- Contains binary distribution of Ant
          lib/                    <-- Binary libraries directory
  	    ant.jar             <-- Ant executable classes
              xml.jar             <-- XML parser required by Ant
      jakarta-taglibs/            <-- Contains source distribution of the
                                      JAKARTA-TAGLIBS libraries
          ... see below ...
  </pre>
  
  <p>Be sure you have set your <code>SERVLET_JAR</code> environment variable
  to point at the <code>servlet.jar</code> containing the servlet and JSP API
  classes, as described above.
  
  
  <h2>Directory Structures</h2>
  
  <p>The distribution archive will contain the following file and directory
  structure:
  
  <ul>
  <li><b>LICENSE</b> - A copy of the Apache Software Foundation
      license under which all Jakarta project software is distributed.
  <li><b>README</b> - A brief README file that contains pointers
      to the documentation that is available.
  <li><b>build</b> - A shell script that builds all of the included custom
      tag libraries on Unix platforms.  See below for more details.
  <li><b>build.bat</b> - A shell script that builds all of the included
      custom tag libraries on Windows platforms.  See below for more details.
  <li><b>build.xml</b> - An XML file that describes the build process for
all
      of the included custom tag libraries.  See the Ant documentation for
      more information about the contents of this file.
  <li><b>doc</b> - A directory containing documentation about the
      JAKARTA-TAGLIBS project as a whole, including this file.  The following
      documents are included:
      <ul>
      <li><a href="index.html">Documentation Index</a>
      <li><a href="binarydist.html">Using the JAKARTA-TAGLIBS Binary
          Distribution</a> (this document)
      <li><a href="sourcedist.html">Using the JAKARTA-TAGLIBS Source
          Distribution</a>
      </ul>
  <li>A directory for each custom tag library included in the JAKARTA-TAGLIBS
      project, where the directory name matches the short name of that project.
      Each directory will contain the following files and subdirectories
      <ul>
      <li><b>build.bat</b> - A shell script that builds this particular
custom
          tag library on Windows platforms.  See below for more details.
      <li><b>build.sh</b> - A shell script that builds this particular custom
tag
          library on Unix platforms.  See below for more details.
      <li><b>build.xml</b> - An XML file that describes the build process
for
          this particular custom tag library.  See the Ant documentation for
          more information on the contents of this file.
      <li><b>conf/</b> - A directory containing configuration and other
resource
          files for this custom tag library, which will normally be used within
          a web application.  At a minimum, the <i>tag library descriptor</i>
          (TLD) file for this custom tag library must be present, in a file that
          is named <code>taglib.tld</code>.
      <li><b>doc/</b> - The source code (Java classes, resource files, HTML
          pages, JSP pages, and so on) for a web application that will contain
          the developer documentation for this tag library.  This web application
          will be combined into a <code>{library}-doc.war</code> web
          application archive in the binary distribution.  See below for more
          information about the internal directory structure of web applications.
      <li><b>examples/</b> - The source code (Java classes, resource files,
          HTML pages, JSP pages, and so on) for a web application that
          demonstrates the use of custom tags within this custom tag library.
          This web application will be combined into a
          <code>{library}-examples.war</code> web application archive in the
          binary distribution.  See below for more information about the
          internal directory structure of web applications.
      <li><b>src/</b> -- The Java source code and resource files of the
classes
          that comprise this custom tag library.  The internal directory
          arrangement within the source directory must reflect the assignment
          of classes to Java packages, in the usual manner.  To avoid name
          clashes, the package name for each custom tag library should be
          <code>org.apache.taglibs.{library}</code> so that multiple
          JAKARTA-TAGLIBS can be used in the same application if desired.
      </ul>
  </ul>
  
  <p>Within the <b>doc/</b> and <b>examples/</b> subdirectories
for each custom
  tag library, the following directory organization is used to contain the source
  components of this application:
  <ul>
  <li><b>conf/</b> -- The <code>web.xml</code> file for this
application, plus
      any other files that should be copied to the WEB-INF subdirectory.
  <li><b>src/</b> -- The Java source code and resource files for this
      application.  Package names are arbitrary, but we recommend using
      <code>org.apache.taglibs.{library}.doc</code> for the documentation
      application, and <code>org.apache.taglibs.{library}.examples</code>
      for the example application.
  <li><b>web/</b> -- The HTML and JSP pages that comprise this application's
      user interface.  The <code>index.html</code> or <code>index.jsp</code>
      page in this directory will be the "home" page of the application when
      it is deployed in a servlet container.
  </ul>
  
  
  <h2>Building JAKARTA-TAGLIBS Libraries</h2>
  
  <p>To build the distribution version of all included custom tag libraries,
  set your current directory to the <code>jakarta-taglibs</code> directory into
  which you unpacked the distribution, and execute the global build script:
  
  <pre>
      build                       <-- Window platforms
      build.sh                    <-- Unix platforms
  </pre>
  
  <p>In addition to the directories described earlier, two additional directory
  hierarchies will be created to contain the results, resulting in the following
  overall organization:
  
  <pre>
  your_home_directory/
      build/                      <-- Contains intermediate form results of
                                      building Jakarta applications
          taglibs/                <-- Contains intermediate form results of
                                      building JAKARTA-TAGLIBS custom libraries
      dist/                       <-- Contains the files that will be included
                                      in binary distributions of Jakarta
                                      applications
          taglibs/                <-- Contains the files that will be included
                                      in the binary distribution of the
                                      JAKARTA-TAGLIBS project, as described in
  				    binary distribution documentation
      jakarta-ant/                <-- Contains binary distribution of Ant
          lib/                    <-- Binary libraries directory
  	    ant.jar             <-- Ant executable classes
              xml.jar             <-- XML parser required by Ant
      jakarta-taglibs/            <-- Contains source distribution of the
                                      JAKARTA-TAGLIBS libraries
  </pre>
  
  <p>When you are working on a particular custom tag library, it is faster to
  rebuild only that particular library while doing development.  To do this,
  change to the top level directory of that custom tag library (for example,
  change to the <code>jakarta-taglibs/jspspec</code> directory to work on the
  JSP Specification Examples custom tag library.  You can now use one of several
  variants of the <b>build</b> script, depending on what you want to do.  In
  each of the following cases use <code>build</code> on Windows systems, or
  <code>build.sh</code> on Unix systems:
  
  <ul>
  <li><b>build</b> -- Update the intermediate form (in the
      <code>../../build/taglibs</code> directory) of the library itself, the
      documentation application, and the example application.  This copies any
      static files that have been changed, and recompiles any Java sourc classes
      that have been changed.  Because this is the most commonly executed
      command, it is the default.
  <li><b>build library</b> -- Update the intermediate form of the library
      classes only.  This is useful when you are making sure it still compiles.
  <li><b>build documentation</b> -- Update the intermediate form of the
      documentation application.  If your servlet container can accept an
      unpacked web application (as Tomcat can), the
      <code>../../build/taglibs/{library}/doc</code> directory can be set
      as the document root, and the application can be executed directly.
  <li><b>build examples</b> -- Update the intermediate form of the examples
      application (including copying the library classes into WEB-INF/classes).
      If your servlet container can accept an unpacked web application (as Tomcat
      can), the <code>../../build/taglibs/{library}/examples</code> directory
can
      be set as the document root, and the application can be executed directly.
  <li><b>build library-dist</b> -- Build and copy the <code>{library}.jar</code>
      and <code>{library}.jar</code> files for this tag library into the
      distribution directory (<code>../../dist/taglibs/{library}</code>).
      These distribution files can be copied directly into web applications
      that wish to use this custom tag library.
  <li><b>build documentation-dist</b> -- Build the <code>{library}-doc.war</code>
      documentation application, and copy it into the distribution directory
      (<code>../../dist/taglibs/{library}</code>).  This application can be
      deployed and executed on any servlet container.
  <li><b>build examples-dist</b> -- Build the <code>{library}-examples.war</code>
      examples application, and copy it into the distribution directory
      (<code>../../dist/taglibs/{library}</code>).  This application can
      be deployed and executed on any servlet container.
  <li><b>build dist</b> -- Short cut command that builds all three
      distribution targets (<code>dist-library</code>, <code>dist-doc</code>,
and
      <code>dist-examples</code>).
  <li><b>build clean</b> -- Deletes the intermediate and distribution results
      for this custom tag library, so that you can rebuild from scratch.
  </ul>
  
  <p>When you perform a global build, the <b>build dist</b> option is invoked
  on each included subproject.
  
  
  <h2>Adding A New JAKARTA-TAGLIBS Custom Tag Library</h2>
  
  <p>Adding a new custom tag library subproject to JAKARTA-TAGLIBS is fairly
  straightforward.  It involves the following steps:
  <ul>
  <li>Create a top-level directory for the new project.  The directory name
      should be a relatively short abbreviation of this custom tag library,
      because it will be used repeatedly in filenames.
  <li>Within that directory, copy the top-level files (<code>build</code>,
      <code>build.bat</code>, and <code>build.bat</code> from one
of the
      existing subprojects, such as <b>jspspec</b>.  Using a text editor,
      customize the <code>build.xml</code> file by changing the value of
      the <code>taglib.name</code> property to the short name of the new
      custom tag library subproject you are building.
  <li>Within the subproject directory, duplicate the directory structure
      from one of the existing subprojects, such as <b>jspspec</b>.
  <li>You should now be able to develop and build your new tag library from
      within its subdirectory, using its own <code>build.xml</code> script.
      The final step is to modify the top level <code>build.xml</code>
      script, so that a global build will include your new library.  The
      required changes are documented within the global <code>build.xml</code>
      file.
  </ul>
  
  
  <div align="center"><hr width="75%"><font size="2">
  $Id: sourcedist.html,v 1.1 2000/04/10 00:52:10 craigmcc Exp $
  </font></div>
  
  </body>
  </html>
  
  
  

Mime
View raw message