glenn 01/06/30 06:39:08
Added: src/doc addtaglib.xml
Log:
Add taglib document data
Revision Changes Path
1.1 jakarta-taglibs/src/doc/addtaglib.xml
Index: addtaglib.xml
===================================================================
<?xml version="1.0"?>
<document url="./addtaglib.xml">
<properties>
<author>Glenn Nielsen</author>
<title>Adding a Custom Tag Library or Extension to JAKARTA-TAGLIBS</title>
</properties>
<body>
<section name="Approval from JAKARTA-TAGLIBS committers" href="Approval">
<p>Submission or creation of a new tag library or ctlx should be
proposed to the taglibs-dev list and only added to the source
repository when approved. Part of that process is selecting
a unique {taglib-name} for the tag library or ctlx. The {taglib-name}
is used as part of the naming convention for directories and
files which make up a tag library in the jakarta-taglibs
source repository.</p>
</section>
<section name="Create the standard taglib directory and file layout" href="Create">
<p>For a tag library, create the directory
<code>jakarta-taglibs/{taglib-name}</code>.
For a CTLX, create the <code>{taglib-name}</code> directory in the
appropriate subdirectory of the <code>jakarta-taglibs/tools/</code> directory.</p>
<p>Copy the files from <code>src/taglib-template</code> into the new directory.
This creates a standard set of directories and files you can
use as a starting point for developing the new taglib. Here is the
listing of directories and files created:
<ul>
<li><b>build.xml</b> - Ant build configuration file</li>
<li><b>doc/</b> - Source files for creating the {taglib-name}-doc.war</li>
<li><b>doc/conf/web.xml</b> - {taglib-name}-doc web application configuration</li>
<li><b>doc/web/</b> - taglib static HTML documentation pages</li>
<li><b>doc/web/changes.html</b> - taglib documentation revision change history</li>
<li><b>examples/</b> - Source files for creating the {taglib-name}-examples.war</li>
<li><b>examples/conf/web.xml</b> - {taglib-name}-examples web application
configuration</li>
<li><b>examples/web/</b> - taglib example static HTML and JSP pages</li>
<li><b>src/org/apache/taglibs/</b> - taglibs java source package directory</li>
<li><b>xml/intro.xml</b> - XML file transformed by src/doc/stylesheets/taglibs.xsl
to create http://jakarta.apache.org/taglibs/doc/{taglib-name}-doc/intro.html</li>
<li><b>xml/taglib-template.xml</b> - XML file transformed by
src/taglib/taglib-doc.xsl
to create your taglib documentation and transformed by src/taglib/tld11.xsl
to create your {taglib-name}.tld Tag Lib Descriptor file.</li>
</ul>
</p>
<p>Make a new directory for your taglib java source code files of:
<pre>
src/org/apache/taglibs/{taglib-name}
</pre>
</p>
<p>Change the name of <code>xml/taglib-template.xml</code> to
<code>xml/{taglib-name}.xml</code>.</p>
<p>You will need to edit the above files to customize them for
your new taglib. Anyplace you see <taglib-name> should be
replaced with either the taglib nickname or taglib display name.</p>
<p>If your tag library will be using any API's or versions of API's
other than servlet.jar check the <code>jakarta-taglibs/build.properties.sample</code>
to see if a property is already configured for it. If not,
add a new property so that the jar files required by your taglib
are available during a jakarta-taglibs build. See your
taglib <code>build.xml</code> file for more information on adding
support to it for additional jar files.</p>
</section>
<section name="Tag Library Coding Standards" href="Standards">
<p>All the classes to implement the tag library should be in
the package <code>org.apache.taglibs.{taglib-name}</code>.</p>
<p>Please review the file HOWTO-RELEASE. This text file
documents the release cycle for tag libraries.</p>
<p>Please put the Apache license at the top of each java source
code file.</p>
<p>Please comment your java source code files so that JavaDoc
can be used to generate API documentation for your taglib.</p>
<p>Please follow standard java coding conventions.</p>
<p>If you are not familiar with how the JSP tag lifecycle affects
the design of JSP tags, please review the document
<a href="guidelines.html">Taglib Developer Guidelines</a>.</p>
<p>Please use the following Java class naming conventions:
<ul>
<li>For java classes that implement a JSP Tag, use a class name
that is the same as the tag name with "Tag" appended. For
example the "newBook" tag would be a class named NewBookTag.</li>
<li>If a tag creates a separate class to implement a bean, attribute,
or script variable for a tag, name it using the tag name.
For example, if the "newBook" tag created a scripting variable
scoped AT_END, the java class to implement the scripting
variable would be named NewBook.</li>
<li>If a tag creates a scripting variable, create a TagExtraInfo
class for it using the tag name followed by TEI. Using the
"newBook" tag example, the TagExtraInfo class would be named
NewBookTEI.</li>
</ul>
</p>
<p>If your custom tag library requires additional JAR files
from external distributions, you may be tempted to check these libraries
in to the CVS repository. This behavior is prohibited by Jakarta project
guidelines, because it causes many errors due to version interdependencies
of shared libraries. Instead, you should include instructions in the user
documentation for your library on how to acquire any additional libraries
or other components that are required.</p>
</section>
<section name="Adding a tag to the tag library" href="Addtag">
<p>Change your directory (cd) to your taglib directory</p>
<p>Add a new <code><tag></code> declaration to your
<code>xml/{taglib-name}.xml</code>.</p>
<p>Develop the necessary java source code files required to implement
the new tag.</p>
<p>Create some static html and jsp pages in the
<code>examples/web/</code> to test the new tag.</p>
</section>
<section name="Building the tag library" href="Building">
<p>Change your directory (cd) to your taglib directory</p>
<p>Refer to the <a href="sourcedist.html">Using the JAKARTA-TAGLIBS Source
Distribution</a>
documentation for information on how to build tag libraries using Ant.</p>
</section>
<section name="Adding the tag library to the jakarta-taglibs repository"
href="Addtaglib">
<p>If you don't have commit privileges for jakarta-taglibs,
zip up your taglib source and post a message to taglibs-dev
proposing the addition of the taglib.</p>
<p>If you have commit privileges, use CVS to add, then commit
the new taglib directories and files. For more information
on using CVS for the jakarta-taglibs repository please see
the section Full Remote CVS Access in the
<a href="http://jakarta.apache.org/site/cvsindex.html";>
Using CVS</a> document.</p>
</section>
<section name="Publishing the tag library to http://jakarta.apache.org/taglibs/";
href="Publish">
<p>Change directory (cd) to the the <code>jakarta-taglibs</code> directory.</p>
<p>Edit the <code>src/doc/index.xml</code> file.
<ul>
Add a <code><newsitem></code> to the top of the <code><news></code>
section of the document announcing the new taglib.
<pre>
<!-- Example news item
<newsitem date="05/19/2001" libname="MyTaglib">
The new cool MyTaglib has been added.
</newsitem>
-->
</pre>
For a tag library, add a <code><taginfo></code> to the
<code><tagindex></code> section.
<pre>
<!-- Example taginfo, initial state should be "develop"
<taginfo name="DBTags" state="develop" branch="">
The DBTags (formerly called JDBC) custom tag library contains
tags which can be used to read from and write to an SQL database.
</taginfo>
-->
</pre>
For a custom tag library extention (CTLX) add a <code><ctlxinfo></code>
to the <code><ctlxindex></code> section.
<pre>
<!-- Example ctlxinfo
<ctlxindex>
<ctlxinfo name="UltraDev" state="develop" branch="">
The UltraDev CTLX adds the ability to use JSP custom tag
libraries when publishing JSP pages using UltraDev 4.0.
</ctlxinfo>
</ctlxindex>
-->
</pre>
</ul>
</p>
<p>Edit your <code>{taglib-name}/xml/intro.xml</code> and add a
<code><newsitem></code> to the <code><news></code> section announcing
the new tag library.</p>
<p>Edit <code>src/doc/project.xml</code>. For a tag library, add a new
<code><item></code> to the <code><menu></code> for "Individual Tag
Libraries".
For a ctlx, add a new <code><item></code> to the <code><menu></code> for
"Custom Tag Library Extensions".</p>
<p>Edit the jakarta-taglibs build.xml.
<ul>
Add a <code><target></code> to build the new taglib or ctlx.
<pre>
<!-- Example taglib target
<target name="log">
<ant dir="./log" target="dist"/>
</target>
-->
<!-- Example ctlx target
<target name="ultradev4">
<ant dir="./tools/UltraDev/4.0/ctlx" target="dist"/>
</target>
-->
</pre>
Add <code>{taglib-name}</code> to the depends attribute of the
<code><target></code> with name "dist" near the bottom of the file.
</ul>
</p>
<p>Do a test distribution build of all the jakarta-taglibs doing an
<code>ant dist</code> build in the main jakarta-taglibs directory.</p>
<p>Generate the Jakarta web site pages by doing an <code>ant
compile.documentation</code>
build in the main jakarta-taglibs directory.</p>
<p>The web pages which would be published to the jakarta site for the taglib
or ctlx will be found in <code>build/{taglib-name}/{taglib-name}-doc/</code>.</p>
<p>Once you have confirmed that everything builds correctly you can
commit all these changes to the jakarta-taglibs CVS repository.</p>
<p>At this point the development state of the taglib is still develop.</p>
<p>Now that the taglib has been added to jakarta-taglibs information
about the taglib will be made available at http://jakarta.apache.org/
following the nightly jakarta-taglibs build.</p>
<p>Each night a script runs which will update the following information
at http://jakarta.apache.org/:
<ul>
<li>The main http://jakarta.apache.org/taglibs page will display
your newsitem and hava a link to the taglib on its left
navigation bar.</li>
<li>Information about this taglib will be available at
http://jakarta.apache.org/taglibs/doc/{taglib-name}-doc/</li>
<li>The documentation for the taglib development version will be at:
http://jakarta.apache.org/taglibs/doc/{taglib-name}-doc/nightly/</li>
<li>Nightly builds of the taglib binary distribution will be available at:
http://jakarta.apache.org/builds/jakarta-taglibs/nightly/projects/{taglib-name}
This is a binary snapshot of the current main development branch of
the taglib.</li>
<li>The taglib main development branch will also be included in the nightly
snapshot builds of the jakarta-taglibs source and binary distributions.</li>
<ul>
<li>http://jakarta.apache.org/builds/jakarta-taglibs/nightly/</li>
<li>http://jakarta.apache.org/builds/jakarta-taglibs/nightly/src/</li>
</ul>
</ul>
</p>
</section>
<section name="Publishing a milestone release" href="Milestone">
<p>See the HOWTO-RELEASE text file for information about when to
do a milestone release.</p>
<p>If the taglib design is fully implemented, you can skip this
step and go right to Publishing a beta release.</p>
<p>Propose to the taglibs-dev list that a milestone release be
published. Once approved by the jakarta-taglib committers
you can perform the milestone release.</p>
<p>Determine the major, minor, and milestone release numbers
for the taglib. Milestone releases start at 1 and are incremented
for each subsequent milestone release.</p>
<p>The <code>{release-name}</code> will be
<code>{taglib-name}-{major}.{minor}-M{milestone-number}</code>.</p>
<p>The filename for this release will be <code>{release-name}.zip</code></p>
<p>Update the jakarta web site by editing <code>src/doc/index.xml</code>:
<ul>
<li>Add a <code><newsitem></code> announcing the milestone release.</li>
<li>Set the <code><taginfo></code> or <code><ctlxinfo></code> branch
attribute for your taglib or ctlx to <code>{release-name}</code>.</li>
</ul>
</p>
<p>Update your jakarta web site documentation by editing
<code>{taglib-name}/xml/intro.xml</code>:
<ul>
<li>Add a <code><newsitem></code> announcing the milestone release.</li>
<li>Uncomment the area in the Download section for downloading
a release of {taglib-name} Tag Library.</li>
<li>Uncomment the area in the Documentation section for viewing
the release documentation of {taglib-name} Tag Library.</li>
</ul>
</p>
<p>Make sure you have committed all your {taglib-name} and
jakarta-taglibs changes to CVS.</p>
<p>Create a branch of the {taglib-name} source in CVS:
<ul>
<li>Change directory (cd) to <code>jakarta-taglibs/{taglib-name}/</code>
<code>cvs tag -b {release-name}</code>.</li>
<li>Your local copy of the <code>jakarta-taglibs/{taglib-name}/</code> will
still be set to the main development branch of your taglib.</li>
</ul>
</p>
<p>Your {taglib-name} release will be made available on the
jakarta.apache.org site once the nightly builds have been
completed.</p>
<p>The documentation for the taglib release will be at:
http://jakarta.apache.org/taglibs/doc/{taglib-name}-doc/{release-name}/</p>
<p>The taglib release will be available for download at:
http://jakarta.apache.org/builds/jakarta-taglibs/releases/{taglib-name}/{release-name}.zip</p>
</section>
<section name="Publishing a beta release" href="Beta">
<p>See the HOWTO-RELEASE text file for information about when to
do a beta release.</p>
<p>Propose to the taglibs-dev list that a beta release be
published. Once approved by the jakarta-taglib committers
you can perform the beta release.</p>
<p>Determine the major, minor, bug fix, and beta release numbers
for the taglib. Beta releases start at 1 and are incremented
for each subsequent beta release.</p>
<p>The <code>{release-name}</code> will be
<code>{taglib-name}-{major}.{minor}.{bug-fix}-B{beta-number}</code>.</p>
<p>The filename for this release will be <code>{release-name}.zip</code></p>
<p>Update the jakarta web site by editing <code>src/doc/index.xml</code>:
<ul>
<li>Add a <code><newsitem></code> announcing the beta release.</li>
<li>Set the <code><taginfo></code> or <code><ctlxinfo></code> branch
attribute for your taglib or ctlx to <code>{release-name}</code>.</li>
<li>Set the <code><taginfo></code> or <code><ctlxinfo></code> state
attribute for your taglib or ctlx to <code>beta</code>.</li>
</ul>
</p>
<p>Update your jakarta web site documentation by editing
<code>{taglib-name}/xml/intro.xml</code>:
<ul>
<li>Add a <code><newsitem></code> announcing the beta release.</li>
<li>Uncomment the area in the Download section for downloading
a release of {taglib-name} Tag Library.</li>
<li>Uncomment the area in the Documentation section for viewing
the release documentation of {taglib-name} Tag Library.</li>
</ul>
</p>
<p>Make sure you have committed all your {taglib-name} and
jakarta-taglibs changes to CVS.</p>
<p>Create a branch of the {taglib-name} source in CVS:
<ul>
<li>Change directory (cd) to <code>jakarta-taglibs/{taglib-name}/</code>
<code>cvs tag -b {release-name}</code>.</li>
<li>Your local copy of the <code>jakarta-taglibs/{taglib-name}/</code> will
still be set to the main development branch of your taglib.</li>
</ul>
</p>
<p>Your {taglib-name} release will be made available on the
jakarta.apache.org site once the nightly builds have been
completed.</p>
<p>The documentation for the taglib release will be at:
http://jakarta.apache.org/taglibs/doc/{taglib-name}-doc/{release-name}/</p>
<p>The taglib release will be available for download at:
http://jakarta.apache.org/builds/jakarta-taglibs/releases/{taglib-name}/{release-name}.zip</p>
</section>
<section name="Publishing an official release" href="Release">
<p>See the HOWTO-RELEASE text file for information about when to
do an official release.</p>
<p>Propose to the taglibs-dev list that an official release be
published. Once approved by the jakarta-taglib committers
you can perform the release.</p>
<p>Determine the major, minor, bug fix release numbers
for the taglib. Beta releases start at 1 and are incremented
for each subsequent beta release.</p>
<p>The <code>{release-name}</code> will be
<code>{taglib-name}-{major}.{minor}.{bug-fix}</code>.</p>
<p>The filename for this release will be <code>{release-name}.zip</code></p>
<p>Update the jakarta web site by editing <code>src/doc/index.xml</code>:
<ul>
<li>Add a <code><newsitem></code> announcing the release.</li>
<li>Set the <code><taginfo></code> or <code><ctlxinfo></code> branch
attribute for your taglib or ctlx to <code>{release-name}</code>.</li>
<li>Set the <code><taginfo></code> or <code><ctlxinfo></code> state
attribute for your taglib or ctlx to <code>released</code>.</li>
</ul>
</p>
<p>Update your jakarta web site documentation by editing
<code>{taglib-name}/xml/intro.xml</code>:
<ul>
<li>Add a <code><newsitem></code> announcing the official release.</li>
<li>Uncomment the area in the Download section for downloading
a release of {taglib-name} Tag Library.</li>
<li>Uncomment the area in the Documentation section for viewing
the release documentation of {taglib-name} Tag Library.</li>
</ul>
</p>
<p>Make sure you have committed all your {taglib-name} and
jakarta-taglibs changes to CVS.</p>
<p>Create a branch of the {taglib-name} source in CVS:
<ul>
<li>Change directory (cd) to <code>jakarta-taglibs/{taglib-name}/</code>
<code>cvs tag -b {release-name}</code>.</li>
<li>Your local copy of the <code>jakarta-taglibs/{taglib-name}/</code> will
still be set to the main development branch of your taglib.</li>
</ul>
</p>
<p>Your {taglib-name} release will be made available on the
jakarta.apache.org site once the nightly builds have been
completed.</p>
<p>The documentation for the taglib release will be at:
http://jakarta.apache.org/taglibs/doc/{taglib-name}-doc/{release-name}/</p>
<p>The taglib release will be available for download at:
http://jakarta.apache.org/builds/jakarta-taglibs/releases/{taglib-name}/{release-name}.zip</p>
</section>
</body>
</document>
