Home
Jakarta Taglibs
JCP Standardized Tag Libraries
Standard-1.0: JSTL 1.0 (1.2)
Standard-1.1: JSTL 1.1 (2.0)
Supported Tag Libaries
Application (1.1)
Benchmark (1.1)
BSF (1.1)
Cache (1.2)
DateTime (1.1)
DBTags (1.1)
I18N (1.1)
Input (1.1)
IO (1.1)
JMS (1.1)
JNDI (1.1)
Log (1.1)
Mailer (1.1)
Page (1.1)
Random (1.1)
Regexp (1.1)
Request (1.1)
Response (1.1)
Scrape (1.1)
Session (1.1)
String (1.1)
XTags (1.1)
Tool Extensions
UltraDev 4.0
Sandbox
Iterators (1.2)
Unstandard (1.2)
Deprecated Tag Libraries
Utility (1.1)
XSL (1.1)
Jakarta Community
Get Involved
Mailing Lists
CVS Repositories
Reference Library
Bug Database
Adding a Custom Tag Library or Extension
New Project Submission
Create the new taglib or CTLX directory and file layout
Tag Library Coding Standards
Adding a tag to the tag library
Building the tag library
Adding the tag library to the jakarta-taglibs repository
Publishing the tag library to http://jakarta.apache.org/taglibs/
Publishing a milestone release
Publishing a beta release
Publishing an official release
Release Manager Actions
New Project Submission

Submission of a new project (tag library or ctlx) must be done according to the process defined in the document New Project Submission. Once a new project is accepted for inclusion in the sandbox, it must conform to the release structure described in this document.

Selecting a unique name for the tag library or ctlx is the first step. 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.

Create the new taglib or CTLX directory and file layout

The directory and file structure for a new tag library or CTLX can be created by using the ant build target new.taglib or new.ctlx.

    ant new.taglib -Dtaglib.name=cooljsp

    Creates a new taglib in the directory jakarta-taglibs/cooljsp.

    ant new.ctlx -Dctlx.name=coolctlx1 -Dctlx.path=tools

    Creates a new CTLX in the directory jakarta-taglibs/tools/coolctlx1.


The xml files created above wull be automatically customized for your new project. Simply make sure that the required properties are properly defined in build.properties.

  • {taglib-name} - replaced with the taglib or ctlx nickname (new.name).
  • {display-name} - replaced with the name used for taglib in documentation (new.name.display).
  • {your-name} - replace with your name as author of taglib (new.author).

If your tag library will be using any API's or versions of API's other than servlet.jar check the jakarta-taglibs/build.properties.sample 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 build.xml file for more information on adding support to it for additional jar files.

Tag Library Coding Standards

All the classes to implement the tag library should be in the package org.apache.taglibs.{taglib-name}.

A project in Jakarta Taglibs must be released according to the rules defined in document How To Release.

Please put the Apache Software Foundation license at the top of each java source code file.

Please put the following cvs tags starting at the second line of the Apache Software Foundation license comment:

 * $Header$
 * $Revision$
 * $Date$
CVS will expand the above tags out to provide revision information inside the source file whenever you commit the file.

Please comment your java source code files so that JavaDoc can be used to generate API documentation for your taglib.

Please follow standard java coding conventions.

Please use the following capitalization conventions when naming tags, attributes, and script variable bean properties.

    The first letter should always be lower case. If the name of a tag, attribute, or property consists of multiple words concatenated together, capitalize the first character of each new word in the name, after the first word. Example: theSecondWord.

If you are not familiar with how the JSP tag lifecycle affects the design of JSP tags, please review the document Taglib Developer Guidelines.

Please use the following Java class naming conventions:

  • 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.
  • 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.
  • 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.

If your custom tag library requires additional JAR files from external distributions, make sure that these dependencies are clearly documented, as well as how to acquire them.

In order to facilitate an easy "out-of-the-box" experience, it is allowed to check these dependencies in the CVS repository of the tag library, so they can be bundled with the example webapp of the tag library.

Adding a tag to the tag library

Change your directory (cd) to your taglib directory

Add a new <tag> declaration to your xml/{taglib-name}.xml.

Develop the necessary java source code files required to implement the new tag.

Create some static html and jsp pages in the examples/web/ to test the new tag. The first line in your example jsp pages must declare the xml doctype using something similar to this: <!doctype html public "-//w3c//dtd html 4.0 transitional//en">. The build of the examples war file will automatically create an html file for each example jsp file. You can put a link in your static html or jsp files to the html file generated from the jsp source to add a view source link. For example, the file foo.jsp would have a corresponding foo.html file generated.

Building the tag library

Change your directory (cd) to your taglib directory

Refer to the Using the JAKARTA-TAGLIBS Source Distribution documentation for information on how to build tag libraries using Ant.

Adding the tag library to the jakarta-taglibs repository

If you don't have commit privileges for jakarta-taglibs, create a zip file of the taglib source and the committer sponsoring your project will add it to the sandbox.

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 Using CVS document.

Publishing the tag library to http://jakarta.apache.org/taglibs/

Change directory (cd) to the the jakarta-taglibs directory.

Edit the src/doc/index.xml file.

    Add a <newsitem> to the top of the <news> section of the document announcing the new taglib.
    <!-- Example news item
         <newsitem date="05/19/2001" libname="MyTaglib">
           The new cool MyTaglib has been added.
         </newsitem>
    -->
    

Edit your {taglib-name}/xml/intro.xml and add a <newsitem> to the <news> section announcing the new tag library.

Edit src/doc/project.xml. For a tag library, add a new <item> to the <menu> for "Individual Tag Libraries". For a ctlx, add a new <item> to the <menu> for "Custom Tag Library Extensions".

Edit the jakarta-taglibs build.xml.

    Add a <target> to build the new taglib or ctlx.
    <!-- 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>
    -->
    
    Add {taglib-name} to the depends attribute of the <target> with name "dist" near the bottom of the file.

Do a test distribution build of all the jakarta-taglibs doing an ant dist build in the main jakarta-taglibs directory.

Generate the Jakarta web site pages by doing an ant compile.documentation build in the main jakarta-taglibs directory.

The web pages which would be published to the jakarta site for the taglib or ctlx will be found in build/{taglib-name}/{taglib-name}-doc/.

Once you have confirmed that everything builds correctly you can commit all these changes to the jakarta-taglibs CVS repository.

At this point the development state of the taglib is still develop.

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.

Each night a script runs which will update the following information at http://jakarta.apache.org/:

  • The main http://jakarta.apache.org/taglibs page will display your newsitem and hava a link to the taglib on its left navigation bar.
  • Information about this taglib will be available at http://jakarta.apache.org/taglibs/doc/{taglib-name}-doc/
  • The documentation for the taglib development version will be at: http://jakarta.apache.org/taglibs/doc/{taglib-name}-doc/nightly/
  • 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.
  • The taglib main development branch will also be included in the nightly snapshot builds of the jakarta-taglibs source and binary distributions.
    • http://jakarta.apache.org/builds/jakarta-taglibs/nightly/
    • http://jakarta.apache.org/builds/jakarta-taglibs/nightly/src/

Publishing a milestone release

See the HOWTO-RELEASE text file for information about when to do a milestone release.

If the taglib design is fully implemented, you can skip this step and go right to Publishing a beta release.

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.

Determine the major, minor, and milestone release numbers for the taglib. Milestone releases start at 1 and are incremented for each subsequent milestone release.

The {release-name} will be {taglib-name}-{major}.{minor}-M{milestone-number}.

The filenames for this release will be jakarta-taglibs-{release-name}.zip and jakarta-taglibs-{release-name}.tar.gz.

Update the jakarta web site by editing src/doc/index.xml:

  • Add a <newsitem> announcing the milestone release.

Update your jakarta web site documentation by editing {taglib-name}/xml/intro.xml:

  • Add a <newsitem> announcing the milestone release.
  • Uncomment the area in the Download section for downloading a release of {taglib-name} Tag Library.
  • Uncomment the area in the Documentation section for viewing the release documentation of {taglib-name} Tag Library.

Update the <revision> section of your xml/{taglib-name}.xml file so that the changes.html file for your taglib is up to date.

Make sure you have committed all your {taglib-name} and jakarta-taglibs changes to CVS.

Create a branch of the {taglib-name} source in CVS:

  • Change directory (cd) to jakarta-taglibs/{taglib-name}/ cvs tag -b {taglib-name}-{major}-{minor}-M{milestone-number}.
  • Your local copy of the jakarta-taglibs/{taglib-name}/ will still be set to the main development branch of your taglib.

Send an email to the taglibs-dev list requesting that the Jakarta-Taglibs Project release manager perform the tag library or CTLX milestone release.

The documentation for the taglib release will be at: http://jakarta.apache.org/taglibs/doc/{taglib-name}-doc/{release-name}/

The taglib release will be available for download at: http://www.apache.org/dist/jakarta/taglibs/{taglib-name}/

Publishing a beta release

See the HOWTO-RELEASE text file for information about when to do a beta release.

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.

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.

The {release-name} will be {taglib-name}-{major}.{minor}.{bug-fix}-B{beta-number}.

The filenames for this release will be jakarta-taglibs-{release-name}.zip and jakarta-taglibs-{release-name}.tar.gz.

Update the jakarta web site by editing src/doc/index.xml:

  • Add a <newsitem> announcing the beta release.

Update your jakarta web site documentation by editing {taglib-name}/xml/intro.xml:

  • Add a <newsitem> announcing the beta release.
  • Uncomment the area in the Download section for downloading a release of {taglib-name} Tag Library.
  • Uncomment the area in the Documentation section for viewing the release documentation of {taglib-name} Tag Library.

Update the <revision> section of your xml/{taglib-name}.xml file so that the changes.html file for your taglib is up to date.

Make sure you have committed all your {taglib-name} and jakarta-taglibs changes to CVS.

Create a branch of the {taglib-name} source in CVS:

  • Change directory (cd) to jakarta-taglibs/{taglib-name}/ cvs tag -b {taglib-name}-{major}-{minor}-{bug-fix}-B{beta-number}.
  • Your local copy of the jakarta-taglibs/{taglib-name}/ will still be set to the main development branch of your taglib.

Send an email to the taglibs-dev list requesting that the Jakarta-Taglibs Project release manager perform the tag library or CTLX beta release.

The documentation for the taglib release will be at: http://jakarta.apache.org/taglibs/doc/{taglib-name}-doc/{release-name}/

The taglib release will be available for download at: http://www.apache.org/dist/jakarta/taglibs/{taglib-name}/

Publishing an official release

See the HOWTO-RELEASE text file for information about when to do an official release.

Propose to the taglibs-dev list that an official release be published. Once approved by the jakarta-taglib committers you can perform the release.

Determine the major, minor, bug fix release numbers for the taglib.

The {release-name} will be {taglib-name}-{major}.{minor}.{bug-fix}.

The filenames for this release will be jakarta-taglibs-{release-name}.zip and jakarta-taglibs-{release-name}.tar.gz.

Update the jakarta web site by editing src/doc/index.xml:

  • Add a <newsitem> announcing the release.

Update your jakarta web site documentation by editing {taglib-name}/xml/intro.xml:

  • Add a <newsitem> announcing the official release.
  • Uncomment the area in the Download section for downloading a release of {taglib-name} Tag Library.
  • Uncomment the area in the Documentation section for viewing the release documentation of {taglib-name} Tag Library.

Update the <revision> section of your xml/{taglib-name}.xml file so that the changes.html file for your taglib is up to date.

Make sure you have committed all your {taglib-name} and jakarta-taglibs changes to CVS.

Create a branch of the {taglib-name} source in CVS:

  • Change directory (cd) to jakarta-taglibs/{taglib-name}/ cvs tag -b {taglib-name}-{major}-{minor}-{bug-fix}.
  • Your local copy of the jakarta-taglibs/{taglib-name}/ will still be set to the main development branch of your taglib.

Send an email to the taglibs-dev list requesting that the Jakarta-Taglibs Project release manager perform the tag library or CTLX release.

The documentation for the taglib release will be at: http://jakarta.apache.org/taglibs/doc/{taglib-name}-doc/{release-name}/

The taglib release will be available for download at: http://www.apache.org/dist/jakarta/taglibs/{taglib-name}/

Release Manager Actions

Prerequisites:

  • The jakarta-taglibs committer performing a release must have a shell account on the apache web server.
  • The jakarta-taglibs committer performing a release must have a PGP key for signing the release. See http://www.apache.org/dist/jakarta/taglibs/KEYS
  • Please add any knew pgp keys to the jakarta-taglibs CVS repository src/site/builds/releases/KEYS file.
  • Publish the new KEYS file to the /www/www.apache.org/dist/jakarta/taglibs directory at www.apache.org.

Building a release:

  • This works for any taglib that uses the common taglib ant build. If the taglib does not use this, you are on your own.
  • Checkout a clean copy of jakarta-taglibs from CVS: cvs co jakarta-taglibs.
  • cd to the directory for the taglib being released: cd jakarta-taglibs/{taglib-name}.
  • Use ant to build the release distribution passing in the release version: ant -Drelease={release-version} -Ddist.dir=../dist/jakarta-taglibs release.
  • Sign the tar.gz and zip files for the taglib release found in the dist directory.

Publishing the release:

  • Publish the release documentation found in the dist dir to the http://jakarta.apache.org/ webiste location identified for the release. Make sure the group write bit is set for all directories and files.
  • Publish the release distributions to the http://www.apache.org/ website
    • Publish the distributions and .asc files found in the dist dir to the /www/www.apache.org/dist/jakarta/taglibs/{taglib-name}/binaries directory at www.apache.org. Make sure the group write bit is set for all directories and files.
    • Change directory cd to the /www/www.apache.org/dist/jakarta/taglibs/{taglib-name} directory at www.apache.org. Remove the soft links to any previous versions and recreate the soft link to all the files in the binaries directory using current as the version. ln -s binaries/jakarta-taglibs-application-1.0.1.zip jakarta-taglibs-application-current.zip
    • Remove any old release distributions no longer needed. Remove any soft links for any old release distributions, then remove the distributions from the binaries directory.
  • Announce the release to announcements@jakarta.apache.org, taglibs-user@jakarta.apache.org, and taglibs-dev@jakarta.apache.org.


Copyright © 2000, Apache Software Foundation