How-to Velocity Dates with dateTool

By Tom posted 04-20-2015 18:32

Hi Everyone
If you create Velocity reports, you have probably struggled with dates! Since there was little to no documentation on the topic, I have decided to document it.

Below is a snippet of Velocity code with examples on how to use dateTool

#set ($thisDoc = $documentDao.getDocument(331117)) ## This just gets an item 331117 is its id

Different ways to get current date
dateTool : $dateTool
dateTool.long : $dateTool.long
dateTool.medium_time : $dateTool.medium_time
dateTool.full_date : $dateTool.full_date
dateTool.get('default','short') : $dateTool.get('default','short')
dateTool.get('yyyy-M-d H:m:s') : $dateTool.get('yyyy-M-d H:m:s')
Example of formatting an arbitrary date from an item:
#set($myDate = $velocityReportUtil.getValueForField($thisDoc, "end_date", $dateFormat))

myDate raw format : $myDate
myDate medium : $dateTool.format('medium',$myDate)

myDate short : $dateTool.format('short',$myDate)

myDate 'yyyy-M-d' : $dateTool.format('yyyy-M-d',$myDate)

The output of the above code is the following, as you can see we have several different variants of current date as well as different output formats of the field named "end_date" from item 331117.

Different ways to get current date
dateTool : 20/04/2015 12:56:23 PM
dateTool.long : 20 April 2015 12:56:23 PM
dateTool.medium_time : 12:56:23 PM
dateTool.full_date : Monday, 20 April 2015
dateTool.get('default','short') : 20/04/2015 12:56 PM
dateTool.get('yyyy-M-d H:m:s') : 2015-4-20 12:56:23
Example of formatting an arbitrary date from an item:
myDate raw format : 05/22/2015 12:00:00 AM
myDate medium : 5/10/2016 12:00:00 AM
myDate short : 5/10/16 12:00 AM
myDate 'yyyy-M-d' : 2016-10-5

More output formats can be found here:

Haven't tried them all but the following codes should work for dateTool.format

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) '

#tutorial #velocity


06-08-2015 16:45

Thanks for writing that up, Tom. 

04-27-2015 13:52

Update for all you users who want a MM/dd/yyyy default format for Jama. Especially for you SOAP users, this is extra useful.
You can now set your Jama internal date/time format to MM/dd/yyyy H:m:s and use $dateTool.getDateFormat in Velocity to parse that date correctly.

See below, I create a dateFormatter object which knows how to parse the date returned from Jama (in MM/dd/yyyy H:m:s format). I can then use that to parse the date $dateFormatter.parse($myDate). Then I can use all of the standard $dateTool.format capabilities.

===================== Example Code =============================

#set ( $dateFormatter = $dateTool.getDateFormat("MM/dd/yyyy H:m:s", $dateTool.getLocale(), $dateTool.getTimeZone()) )
#set ($thisDoc = $documentDao.getDocument(331117)) ## This just gets an item 331117 is its id
#set($myDate = $velocityReportUtil.getValueForField($thisDoc, "end_date", $dateFormat))

#set($formattedDate = $dateFormatter.parse($myDate))

myDate raw format : $myDate
formattedDate raw format : $formattedDate
formattedDate medium : $dateTool.format('medium',$formattedDate)
formattedDate short : $dateTool.format('short',$formattedDate)
formattedDate 'yyyy-M-d' : $dateTool.format('yyyy-M-d',$formattedDate)
===================== Example Output =============================
myDate raw format : 05/22/2015 12:00:00 AM
formattedDate raw format : Fri May 22 12:00:00 PDT 2015
formattedDate medium : May 22, 2015 12:00:00 PM
formattedDate short : 5/22/15 12:00 PM
formattedDate 'yyyy-M-d' : 2015-5-22

04-20-2015 21:49

<P> Start Time: $dateTool.format( 'MMMM d, yyyy h:m:s a',$dateTool.getSystemDate()) </p>
<P> End Time: $dateTool.format( 'MMMM d, yyyy h:m:s a',$dateTool.getSystemDate()) </p>

this is how I used the date tool to display how much time a report would take to generate.

hope this is helpful.

04-20-2015 20:50

It also looks like in order for dateTool to work correctly, Jama needs to be set up with dd/MM/yyyy format for Java. This is set via the 'root' login.

Ideally this wouldn't be necessary. Is there any way to get Velocity to correctly parse the date when Jama is set to use MM/dd/yyyy Java format? I couldn't seem to figure out how to create a new dateFormatter object that gets passed into $velocityReportUtil.getValueForField