2010-04-14 - Jakarta Taglibs has been retired.

For more information, please explore the Attic.

Jakarta Project: Datetime Tag Library

Version: 1.0.1

Table of Contents

Overview

The DATETIME custom tag library contains tags which can be used to handle date and time related functions.

Tags are provided for formatting a Date for output, generating a Date from HTML form input, using time zones, and localization.

Requirements

This custom tag library requires no software other than a servlet container that supports the JavaServer Pages Specification, version 1.1 or higher.

Configuration

Follow these steps to configure your web application with this tag library:

To use the tags from this library in your JSP pages, add the following directive at the top of each page:

<%@ taglib uri="http://jakarta.apache.org/taglibs/datetime-1.0" prefix="dt" %>

where "dt" is the tag name prefix you wish to use for tags from this library. You can change this value to any prefix you like.

Tag Summary

Date Tags
currentTime Gets the current time in milliseconds since Jan 1, 1970 GMT.
format Formats a date in milliseconds since Jan 1, 1970 GMT for output as a date string.
parse Parses a date string and outputs the time in milliseconds since Jan 1, 1970 GMT.
timeZone Create a time zone script variable for use with the parse or format tags.
 
Localized Date Selections
timeZonesLoop through all time zones.
monthsLoop through the months of the year.
weekdaysLoop through the days of the week.
amPmsLoop through the am/pm names.
erasLoop through the era names.
 

Tag Reference

currentTime Availability: 1.0

Gets the current time in milliseconds since Jan 1, 1970 GMT.

Tag Bodyempty    
Restrictions

None

AttributesNone
VariablesNone
Examples Display the current time  
 



The current time in milliseconds since midnight January 1, 1970 GMT is:
<dt:currentTime/>
 
          

format Availability: 1.0

Formats a date in milliseconds since Jan 1, 1970 GMT for output as a date string.

Tag BodyJSP    
Restrictions

The body of the tag must be a Date in milliseconds since Jan 1, 1970 GMT.

AttributesNameRequired Runtime Expression Evaluation Availability
 pattern  No   No  1.0
 

Date Time Pattern Format string to use for formatting the date.

 patternId  No   No  1.0
 

Name of a script variable which contains a Date Time Pattern Format string to use for formatting the date.

 timeZone  No   No  1.0
 

Name of a timeZone script id variable. Date formatting is adjusted for the time zone.

 date  No   Yes  1.0
 

Set the date to format by passing in a Date object using a runtime expression value.

 default  No   No  1.0
 

Set the default text to output if their is not a valid date input as a date object or in the tag body.

 locale  No   No  1.0
 

Set to "true" to use the clients locale, if known, when formatting date.

 localeRef  No   No  1.0
 

Specify the name of a page, session, application, or request scope attribute of type java.util.Locale to use for locale.

VariablesNone
Examples Display the current time formatted  
 



The current time is:
<dt:format pattern="MM/dd/yyyy hh:mm"><dt:currentTime/></dt:format>

          

parse Availability: 1.0

Parses a date string and outputs the time in milliseconds since Jan 1, 1970 GMT.

Tag BodyJSP    
Restrictions

The body of the tag is used as the Date string to parse.

AttributesNameRequired Runtime Expression Evaluation Availability
 pattern  No   No  1.0
 

Date Time Pattern Format string to use when parsing the date string.

 patternId  No   No  1.0
 

Name of a script variable which contains a Date Time Pattern Format string to use when parsing the date.

 timeZone  No   No  1.0
 

Name of a timeZone script id variable. The date is adjusted for the time zone.

 locale  No   No  1.0
 

Set to "true" to use the clients locale, if known, when formatting date.

 localeRef  No   No  1.0
 

Specify the name of a page, session, application, or request scope attribute of type java.util.Locale to use for locale.

VariablesNone
Examples Output the date in milliseconds for a specific day, month, and year  
 



<req:setAttribute name="pattern">yyyy MM dd</req:setAttribute>
<dt:parse patternId="pattern">2000 11 5</dt:parse>

          

timeZone Availability: 1.0

Create a time zone script variable for use with the parse or format tags.

Tag BodyJSP    
Restrictions

The body of the tag must be empty or a valid time zone ID. If a valid time zone ID is not found, the default time zone for the server is used.

AttributesNameRequired Runtime Expression Evaluation Availability
 id  Yes   No  1.0
 

Script variable id of the time zone for use with the parse and format tags.

VariablesNameScopeAvailability
  id attribute value   End of tag to end of page  1.0
 

A TimeZone for use with parse and format tags.

 PropertiesNone
Examples Sets the time zone to America/Chicago  
 



<dt:timeZone id="tz">America/Chicago</dt:timeZone>
The current time in America/Chicago is:
<dt:format timeZone="tz"><dt:currentTime/></dt:format>
 
          

timeZones Availability: 1.0

Loop through all time zones.

Tag BodyJSP    
Restrictions

None

AttributesNameRequired Runtime Expression Evaluation Availability
 id  Yes   No  1.0
 

Script variable id for use with standard jsp:getProperty tag.

 locale  No   No  1.0
 

Set to "true" to use the clients locale, if known, when formatting time zone display names.

 localeRef  No   No  1.0
 

Specify the name of a page, session, application, or request scope attribute of type java.util.Locale to use for locale.

 style  No   No  1.0
 

Style of display name, either "SHORT" or "LONG".

VariablesNameScopeAvailability
  id attribute value   Nested within tag  1.0
 

TimeZones Bean

 PropertiesNameGetSetAvailability
   zoneId Yes No 1.0
  

Returns the current time zone ID.

   displayName Yes No 1.0
  

Returns the current time zone display name.

Examples Generate a time zone select box  
 



Select a Time Zone
<select name="timeZone">
 <dt:timeZones id="tz">
  <option value="<jsp:getProperty name="tz" property="zoneId"/>">
  <jsp:getProperty name="tz" property="zoneId"/>
  <jsp:getProperty name="tz" property="displayName"/>
 </dt:timeZones>
</select>

          

months Availability: 1.0

Loop through the months of the year.

Tag BodyJSP    
Restrictions

None

AttributesNameRequired Runtime Expression Evaluation Availability
 id  Yes   No  1.0
 

Script variable id for use with standard jsp:getProperty tag.

 locale  No   No  1.0
 

Set to "true" to use the clients locale, if known, when listing the month names.

 localeRef  No   No  1.0
 

Specify the name of a page, session, application, or request scope attribute of type java.util.Locale to use for locale.

VariablesNameScopeAvailability
  id attribute value   Nested within tag  1.0
 

Months of the year Bean

 PropertiesNameGetSetAvailability
   monthOfYear Yes No 1.0
  

Returns the number of the month of the year.

   month Yes No 1.0
  

Returns the full name of the month of the year.

   shortMonth Yes No 1.0
  

Returns the short name of the month of the year.

Examples Generate a Month select box  
 



Select a Month
<select name="month">
 <dt:months id="mon">
  <option value="<jsp:getProperty name="mon" property="monthOfYear"/>">
  <jsp:getProperty name="mon" property="month"/>
 </dt:months>
</select>

          

weekdays Availability: 1.0

Loop through the days of the week.

Tag BodyJSP    
Restrictions

None

AttributesNameRequired Runtime Expression Evaluation Availability
 id  Yes   No  1.0
 

Script variable id for use with standard jsp:getProperty tag.

 locale  No   No  1.0
 

Set to "true" to use the clients locale, if known, when listing the week day names.

 localeRef  No   No  1.0
 

Specify the name of a page, session, application, or request scope attribute of type java.util.Locale to use for locale.

VariablesNameScopeAvailability
  id attribute value   Nested within tag  1.0
 

Days of the week Bean

 PropertiesNameGetSetAvailability
   dayOfWeek Yes No 1.0
  

Returns the number of the day of the week.

   weekday Yes No 1.0
  

Returns the full name of the day of the week.

   shortWeekday Yes No 1.0
  

Returns the short name of the day of the week.

Examples Generate a Week Day select box  
 



Select a Week Day
<select name="weekday">
 <dt:weekdays id="day">
  <option value="<jsp:getProperty name="day" property="dayOfWeek"/>">
  <jsp:getProperty name="day" property="weekday"/>
 </dt:weekdays>
</select>

          

amPms Availability: 1.0

Loop through the am/pm names.

Tag BodyJSP    
Restrictions

None

AttributesNameRequired Runtime Expression Evaluation Availability
 id  Yes   No  1.0
 

Script variable id for use with standard jsp:getProperty tag.

 locale  No   No  1.0
 

Set to "true" to use the clients locale, if known, when listing the am/pm names.

 localeRef  No   No  1.0
 

Specify the name of a page, session, application, or request scope attribute of type java.util.Locale to use for locale.

VariablesNameScopeAvailability
  id attribute value   Nested within tag  1.0
 

Am/Pm names Bean

 PropertiesNameGetSetAvailability
   name Yes No 1.0
  

Returns the am/pm name.

Examples Generate an am/pm select box  
 



Select AM or PM:
<select name="ampm">
 <dt:ampms id="ap">
  <option value="<jsp:getProperty name="ap" property="name"/>">
  <jsp:getProperty name="ap" property="name"/>
 </dt:ampms>
</select>

          

eras Availability: 1.0

Loop through the era names.

Tag BodyJSP    
Restrictions

None

AttributesNameRequired Runtime Expression Evaluation Availability
 id  Yes   No  1.0
 

Script variable id for use with standard jsp:getProperty tag.

 locale  No   No  1.0
 

Set to "true" to use the clients locale, if known, when listing the era names.

 localeRef  No   No  1.0
 

Specify the name of a page, session, application, or request scope attribute of type java.util.Locale to use for locale.

VariablesNameScopeAvailability
  id attribute value   Nested within tag  1.0
 

Era names Bean

 PropertiesNameGetSetAvailability
   name Yes No 1.0
  

Returns the era name.

Examples Generate an era select box  
 



Select an Era:
<select name="era">
 <dt:era id="era">
  <option value="<jsp:getProperty name="era" property="name"/>">
  <jsp:getProperty name="era" property="name"/>
 </dt:era>
</select>

          

Date Time Pattern Format

To specify the time format use a time pattern string. In this pattern, all ASCII letters are reserved as pattern letters, which are defined as the following:

 Symbol   Meaning                Presentation       Example
 ------   -------                ------------       -------
 G        era designator         (Text)             AD
 y        year                   (Number)           1996
 M        month in year          (Text & Number)    July & 07
 d        day in month           (Number)           10
 h        hour in am/pm (1~12)   (Number)           12
 H        hour in day (0~23)     (Number)           0
 m        minute in hour         (Number)           30
 s        second in minute       (Number)           55
 S        millisecond            (Number)           978
 E        day in week            (Text)             Tuesday
 D        day in year            (Number)           189
 F        day of week in month   (Number)           2 (2nd Wed in July)
 w        week in year           (Number)           27
 W        week in month          (Number)           2
 a        am/pm marker           (Text)             PM
 k        hour in day (1~24)     (Number)           24
 K        hour in am/pm (0~11)   (Number)           0
 z        time zone              (Text)             Pacific Standard Time
 '        escape for text        (Delimiter)
 ''       single quote           (Literal)          '
 
The count of pattern letters determine the format.

(Text): 4 or more pattern letters--use full form, < 4--use short or abbreviated form if one exists.

(Number): the minimum number of digits. Shorter numbers are zero-padded to this amount. Year is handled specially; that is, if the count of 'y' is 2, the Year will be truncated to 2 digits.

(Text & Number): 3 or over, use text, otherwise use number.

Any characters in the pattern that are not in the ranges of ['a'..'z'] and ['A'..'Z'] will be treated as quoted text. For instance, characters like ':', '.', ' ', '#' and '@' will appear in the resulting time text even they are not embraced within single quotes.

A pattern containing any invalid pattern letter will result in a thrown exception during formatting or parsing.

Examples Using the US Locale:

 Format Pattern                    Result
 --------------                    -------
 "yyyy.MM.dd G 'at' hh:mm:ss z"    1996.07.10 AD at 15:08:56 PDT
 "EEE, MMM d, ''yy"                Wed, July 10, '96
 "h:mm a"                          12:08 PM
 "hh 'o''clock' a, zzzz"           12 o'clock PM, Pacific Daylight Time
 "K:mm a, z"                       0:00 PM, PST
 "yyyyy.MMMMM.dd GGG hh:mm aaa"    1996.July.10 AD 12:08 PM
 

Examples

See the example application datetime-examples.war for examples of the usage of the tags from this custom tag library.

Java Docs

Java programmers can view the java class documentation for this tag library as javadocs.

Revision History

Review the complete revision history of this tag library.