DateTool - Documentation topics on: calendar,date format,date formatting,dates,datetool,parse dates,velocity date and calendar tools,velocity date tool,velocity tools,.

DateTool

The DateTool is a Velocity viewtool which provides methods to manipulate and display dates and times in Velocity.

The following example shows how the Date Viewtool is mapped in the toolbox-xml file:

    <tool>
        <key>date</key>
        <scope>request</scope>
        <class>org.apache.velocity.tools.generic.DateTool</class>
    </tool>

The DateTool makes it easy to:

  • Retrieve the current date
  • Format date objects as Strings
  • Parse Strings into date objects

Date Formats

The DateTool uses the Java SimpleDateFormat. When converting between date objects and Strings, you may specify the format using following symbols in the format string:

SymbolDescriptionValue TypeExamples
GEraTextAD, BC
yYear (full)Number1996, 2017
yyYear (last 2 digits)Number96, 17
MMonthString and Number July & 07 
MMMMonth name
(abbrev.)
TextJul, Dec
MMMMMonth name
(full name)
TextJuly, December
dDay of monthNumber3, 27
ddDay of month (zero-padded)Number03, 27
hhour in am/pm (1~12)Number) 12 
Hhour in day (0~23)Number) 0 
mMinuteNumber7, 49
mmMinute (zero-padded)Number07, 49
sSecondNumber1, 55
ssSecond (zero-padded)Number01, 55
SMillisecondNumber978
EDay of weekStringWednesday
EEEDay of week (abbrev.)StringWed
DDay of yearNumber189
FOccurrence of Day in monthNumber2 (e.g. 2nd Wednesday in July)
wWeek of yearNumber27
WWeek of monthNumber2
aAM/PMStringPM
kHour (24 hour time)Number) 24 
KHour (as AM/PM)Number) 0 
zTime zoneTextPacific Standard Time
zzzTime zone (abbrev.)TextPST
'Literal text delimiterText'Date: '
''Embedded single quoteLiteral''

Examples

Format StringExample Date (for Tue, July 3, 2016)
“E, MMMM d”“Tue, July 3”
“EEE, M-d (H:m)”“Tuesday, 7-3 (14:12)”
“'ABC' E '' MMM dd”“ABC Tue ' Jul 03”

Properties and Methods

The following are some commonly used DateTool properties and methods:

ValueReturn ValueExample Result
$dateCurrent date & time, in default formatOct 19, 2003 9:54:50 PM
$date.longCurrent date & time, in “long” formatOctober 19, 2003 9:54:50 PM PDT
$date.medium_timeCurrent time, in “medium_time” format9:54:50 PM
$date.full_dateCurrent date, in “full_date” formatSunday, October 19, 2003
$date.get('default','short')Current date & time, in “short” formatOct 19, 2003 9:54 PM
$date.get('yy-M-d H:m:s')Current date & time, in the specified format03-10-19 21:54:50`
$date.format('medium',$myDate)Format the date in the $myDate object using “medium” date formatOct 7, 2003 3:14:50 AM
$date.getDate()A Date object for the current date & time
$date.getYear()The current year2003
$date.getMonth()The current month10
$date.getDay()The current day of the month19

In addition, the DateTool supports many additional properties and methods; for a detailed list of DateTool methods, please see the DateTool Javadocs.

Parsing Date Strings

You can extract date objects from date strings using the toDate method, and supplying the appropriate format string, as in the following examples:

#set( $dateObj = $date.toDate( "yyyy-M-d H:m:s",           "2003-10-19 21:54:50") )
#set( $dateObj = $date.toDate( "yyyy-MM-dd'T'HH:mm:ss'Z'", "2016-05-06T20:42:26Z") )

Adding and Subtracting Dates

You can add time to a calendar object by ????????????

Example {AddSubtractExample}

The following example code retrieves a calendar object and adds 24 hours to the time of the object:

<p>Original Date: $date</p>

## Get a Java Calendar Object
#set( $x = $date.calendar )

## Add 24 hours (int code 10)
$x.add( 10, 24 )

## Display the result
<p>New Date :${esc.d}x.time</p>

Multilingual Dates and Times

By default, the date tool will display all date and time related names using the default language, regardless of the language of the page or content where the DateTool is being called from. However you may set the locale used by the DateTool using Velocity, and then specify the locale to use when calling the DateTool methods.

The following example code demonstrates how to call DateTool methods using the language currently set for the page or content where the DateTool is being used:

## Get and display the month and day of week using the default language
#set( $defaultLocale = $date.getLocale() )
<p>Default Locale (${defaultLocale.language}-${defaultLocale.country}): $date.format("MMMM E", $date.getDate(), $defaultLocale)</p>

## Get the user's currently selected dotCMS language and construct the language code for it
#set( $language = $globalvars.getLanguage( $request.getSession().getAttribute('com.dotmarketing.htmlpage.language') ) )
#set( $language = "$language.getLanguageCode()" )
#set( $country = "$language.getCountryCode()" )
#set( $languageCode = "${languageCode}-${countryCode}" )

## Get the locale and display the month and day of week using the user's currently selected language
#set( $locale = $defaultLocale.forLanguageTag( $languageCode ) )
<p>Current Language (${locale.language}-${locale.country}): $date.format("MMMM E", $date.getDate(), $locale)</p>

Java Calendar Constants

Here are the calendar constants - these are used with a java calendar in order to add/subtract and manipulate a date by a particular dimension:

java.util.Calendar
AM 0
AM_PM 9
APRIL 3
AUGUST 7
DATE 5
DAY_OF_MONTH 5
DAY_OF_WEEK 7
DAY_OF_WEEK_IN_MONTH 8
DAY_OF_YEAR 6
DECEMBER 11
DST_OFFSET 16
ERA 0
FEBRUARY 1
FIELD_COUNT 17
FRIDAY 6
HOUR 10
HOUR_OF_DAY 11
JANUARY 0
JULY 6
JUNE 5
LONG 2
MARCH 2
MAY 4
MILLISECOND 14
MINUTE 12
MONDAY 2
MONTH 2
NOVEMBER 10
OCTOBER 9
PM 1
SATURDAY 7
SECOND 13
SEPTEMBER 8
SHORT 1
SUNDAY 1
THURSDAY 5
TUESDAY 3
UNDECIMBER 12
WEDNESDAY 4
WEEK_OF_MONTH 4
WEEK_OF_YEAR 3
YEAR 1
ZONE_OFFSET 15

Javadoc link: Date Tool