You are viewing a plain text version of this content. The canonical link for it is here.
Posted to taglibs-dev@jakarta.apache.org by cr...@locus.apache.org on 2000/04/10 02:52:11 UTC
cvs commit: jakarta-taglibs/doc binarydist.html index.html sourcedist.html
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><taglib></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><taglib></code> element to your web application deployment
descriptor (<code>/WEB-INF/web.xml)</code>) file. An example entry might
look like this:
<pre>
<taglib>
<taglib-uri>http://jakarta.apache.org/taglibs/{library}</taglib-uri>
<taglib-location>/WEB-INF/{library}.tld</taglib-location>
</taglib>
</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><%@ taglib%gt;</code> directive identifying the URI of the library
you want to use (which must match the value you specified in the
<code><taglib-uri></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>
<%@ taglib uri="http://jakarta.apache.org/taglibs/{library}" prefix="x" %>
</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>
<x:magic/>
</pre>
or, if this tag required attributes and perhaps some body text:
<pre>
<x:magic id="beanName" name="xyz">
... Some body text and/or nested tags ...
</x:magic>
</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>