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.
This custom tag library requires no software other than a servlet container that supports the JavaServer Pages Specification, version 1.1 or higher.
Follow these steps to configure your web application with this tag library:
<taglib> <taglib-uri>http://jakarta.apache.org/taglibs/datetime-1.0</taglib-uri> <taglib-location>/WEB-INF/datetime.tld</taglib-location> </taglib>
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.
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. |
dateFormatSymbols | Parses a date string and outputs the time in milliseconds since Jan 1, 1970 GMT. |
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. |
timeZones | Loop through all time zones. |
months | Loop through the months of the year. |
weekdays | Loop through the days of the week. |
amPms | Loop through the am/pm names. |
eras | Loop through the era names. |
currentTime | Availability: 1.0 | ||||
Gets the current time in milliseconds since Jan 1, 1970 GMT. |
|||||
Tag Body | empty | ||||
Restrictions |
None |
||||
Attributes | None | ||||
Variables | None | ||||
Examples | Display the current time | ||||
|
format | Availability: 1.0 | ||||
Formats a date in milliseconds since Jan 1, 1970 GMT for output as a date string. |
|||||
Tag Body | JSP | ||||
Restrictions |
The body of the tag must be a Date in milliseconds since Jan 1, 1970 GMT. |
||||
Attributes | Name | Required | 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. |
|||||
symbolsRef | No | Yes | 1.1 | ||
Specify the name of a page, session, application, or request scope attribute of type java.text.DateFormatSymbols to use for symbols. |
|||||
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. |
|||||
Variables | None | ||||
Examples | Display the current time formatted | ||||
|
dateFormatSymbols | Availability: 1.1 | ||||
Create DateFormatSymbols object that will be used for formating. |
|||||
Tag Body | EMPTY | ||||
Restrictions |
This tag must be placed early in the page (before call of format tag with symbolsRef attribute) |
||||
Attributes | Name | Required | Runtime Expression Evaluation | Availability | |
id | Yes | Yes | 1.1 | ||
Script variable id for use with standard jsp:getProperty tag and as an attribute to other tags in this tag library. |
|||||
baseName | Yes | Yes | 1.1 | ||
Specify the name to locate ResourceBundle |
|||||
locale | No | No | 1.1 | ||
Set to "true" to use the clients locale, if known, when formatting date. |
|||||
localeRef | No | No | 1.1 | ||
Specify the name of a page, session, application, or request scope attribute of type java.util.Locale to use for locale. |
|||||
scope | No | No | 1.1 | ||
Specify the scope that will be used for store DateFormatSymbols variable |
|||||
Variables | Name | Scope | Availability | ||
id attribute value | Start of tag to end of page | 1.1 | |||
The scripting variable declared allows other tags or scriptlets to access the DateFormatSymbols defined by this tag. |
|||||
Properties | None | ||||
Examples | Display the current time formatted | ||||
|
parse | Availability: 1.0 | ||||
Parses a date string and outputs the time in milliseconds since Jan 1, 1970 GMT. |
|||||
Tag Body | JSP | ||||
Restrictions |
The body of the tag is used as the Date string to parse. |
||||
Attributes | Name | Required | 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. |
|||||
Variables | None | ||||
Examples | Output the date in milliseconds for a specific day, month, and year | ||||
|
timeZone | Availability: 1.0 | ||||
Create a time zone script variable for use with the parse or format tags. |
|||||
Tag Body | JSP | ||||
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. |
||||
Attributes | Name | Required | Runtime Expression Evaluation | Availability | |
id | Yes | No | 1.0 | ||
Script variable id of the time zone for use with the parse and format tags. |
|||||
Variables | Name | Scope | Availability | ||
id attribute value | End of tag to end of page | 1.0 | |||
A TimeZone for use with parse and format tags. |
|||||
Properties | None | ||||
Examples | Sets the time zone to America/Chicago | ||||
|
timeZones | Availability: 1.0 | ||||
Loop through all time zones. |
|||||
Tag Body | JSP | ||||
Restrictions |
None |
||||
Attributes | Name | Required | 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". |
|||||
Variables | Name | Scope | Availability | ||
id attribute value | Nested within tag | 1.0 | |||
TimeZones Bean |
|||||
Properties | Name | Get | Set | Availability | |
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 | ||||
|
months | Availability: 1.0 | ||||
Loop through the months of the year. |
|||||
Tag Body | JSP | ||||
Restrictions |
None |
||||
Attributes | Name | Required | 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. |
|||||
Variables | Name | Scope | Availability | ||
id attribute value | Nested within tag | 1.0 | |||
Months of the year Bean |
|||||
Properties | Name | Get | Set | Availability | |
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 | ||||
|
weekdays | Availability: 1.0 | ||||
Loop through the days of the week. |
|||||
Tag Body | JSP | ||||
Restrictions |
None |
||||
Attributes | Name | Required | 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. |
|||||
Variables | Name | Scope | Availability | ||
id attribute value | Nested within tag | 1.0 | |||
Days of the week Bean |
|||||
Properties | Name | Get | Set | Availability | |
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 | ||||
|
amPms | Availability: 1.0 | ||||
Loop through the am/pm names. |
|||||
Tag Body | JSP | ||||
Restrictions |
None |
||||
Attributes | Name | Required | 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. |
|||||
Variables | Name | Scope | Availability | ||
id attribute value | Nested within tag | 1.0 | |||
Am/Pm names Bean |
|||||
Properties | Name | Get | Set | Availability | |
name | Yes | No | 1.0 | ||
Returns the am/pm name. |
|||||
Examples | Generate an am/pm select box | ||||
|
eras | Availability: 1.0 | ||||
Loop through the era names. |
|||||
Tag Body | JSP | ||||
Restrictions |
None |
||||
Attributes | Name | Required | 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. |
|||||
Variables | Name | Scope | Availability | ||
id attribute value | Nested within tag | 1.0 | |||
Era names Bean |
|||||
Properties | Name | Get | Set | Availability | |
name | Yes | No | 1.0 | ||
Returns the era name. |
|||||
Examples | Generate an era select box | ||||
|
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
See the example application datetime-examples.war for examples of the usage of the tags from this custom tag library.
Java programmers can view the java class documentation for this tag library as javadocs.
Review the complete revision history of this tag library.