Freemarker Built-ins for dates

Built-ins for dates
Page Contents

string (when used with a date value)

date, time, datetime (when used with a date value)

iso_...

string (when used with a date value)
This built-in converts a date to a string, with the specified formatting. (when the default format dictated by the date_format, time_format and datetime_format settings of FreeMarker are good for you, then you do not need this built-in.)
The format can be one of the predefined formats, or you can specify the formatting pattern explicitly.
The predefined formats are short, medium, long, and full which define how verbose the resulting text will be. For example, if the locale of the output is U.S. English, and the time zone is the U.S. Pacific Time zone, then this:

${openingTime?string.short}
${openingTime?string.medium}
${openingTime?string.long}
${openingTime?string.full}

${nextDiscountDay?string.short}
${nextDiscountDay?string.medium}
${nextDiscountDay?string.long}
${nextDiscountDay?string.full}

${lastUpdated?string.short}
${lastUpdated?string.medium}
${lastUpdated?string.long}
${lastUpdated?string.full} 

will prints something like this:

12:45 PM
12:45:09 PM
12:45:09 PM CEST
12:45:09 PM CEST

4/20/07
Apr 20, 2007
April 20, 2007
Friday, April 20, 2007

4/20/07 12:45 PM
Apr 20, 2007 12:45:09 PM
April 20, 2007 12:45:09 PM CEST
Friday, April 20, 2007 12:45:09 PM CEST 

The exact meaning of short, medium, long, and full depends on the current locale (language). Furthermore, it is specified not by FreeMarker, but the Java platform implementation you run FreeMarker on.
For dates that contains both date and time part, you can specify the length of the date and time part independently:

${lastUpdated?string.short_long} <#-- short date, long time -->
${lastUpdated?string.medium_short} <#-- medium date, short time --> 

will output:

4/8/03 9:24:44 PM PDT
Apr 8, 2003 9:24 PM 

Note that ?string.short is the same as ?string.short_short, ?string.medium is the same as ?string.medium_medium, etc.
Warning!
Unfortunately, because of the limitations of the Java platform, it can happen that you have date variables in the data-model, where FreeMarker can't decide if the variable stores only date part (year, month, day), only time part (hour, minute, second, millisecond) or both. In this case, FreeMarker don't know how to display the date when you write something like ${lastUpdated?string.short} or simply ${lastUpdated}, and thus it will stop with error. To prevent this, you can help FreeMarker with the ?date, ?time and ?datetime built-ins . For example: ${lastUpdated?datetime?string.short}. Ask the programmer if certain variables of the data-model has this problem, or always use ?date, ?time and ?datetime built-ins.
Instead of using the predefined formats, you can specify the formatting pattern explicitly with ?string(pattern_string). The pattern uses Java date format syntax . Example:

${lastUpdated?string("yyyy-MM-dd HH:mm:ss zzzz")}
${lastUpdated?string("EEE, MMM d, ''yy")}
${lastUpdated?string("EEEE, MMMM dd, yyyy, hh:mm:ss a '('zzz')'")} 

will output:

2003-04-08 21:24:44 Pacific Daylight Time
Tue, Apr 8, '03
Tuesday, April 08, 2003, 09:24:44 PM (PDT) 

Note
Unlike with the predefined formats, you never need to use ?date, ?time and ?datetime with explicitly given patterns, since with the pattern you tell FreeMarker what parts of the date to show. However, FreeMarker will trust you blindly, so you can show "noise"if you display parts that are actually not stored in the variable. For example, ${openingTime?string("yyyy-MM-dd hh:mm:ss a")}, where openingTime stores only time, will display 1970-01-01 09:24:44 PM.
The pattern string also can be "short", "medium", ..., "short_medium", ...etc. These are the same as if you would use the predefined formats with the dot syntax: someDate?string("short") and someDate?string.short are equivalent.
See also: the interpolation of dates
date, time, datetime (when used with a date value)
These built-ins can be used to specify which parts of the date variable are in use:

date: Only the year, month and day parts are used.

time: Only the hour, minute, second and millisecond parts are used.

datetime: Both the date and the time parts are used.

In optimal case, you do not need to use these built-ins. Unfortunately, because of the technical limitations of the Java platform, FreeMarker sometimes can't find out which parts of the date are in use (i.e. only the year+month+day, or only hour+minute+second+millisecond, or both); ask the programmers which variables has this problem. If FreeMarker has to execute an operation where this information is needed -- such as displaying the date as text -- but it does not know which parts are in use, it will stop with error. This is when you have to use these built-ins. For example, assume openingTime is a such problematic variable:

<#assign x = openingTime> <#-- no problem can occur here -->
${openingTime?time} <#-- without ?time it would fail -->
<#-- For the sake of better understanding, consider this: -->
<#assign openingTime = openingTime?time>
${openingTime} <#-- this will work now --> 

There is another usage of these built-ins: to truncate dates. For example:

Last updated: ${lastUpdated} <#-- assume that lastUpdated is a date-time value -->
Last updated date: ${lastUpdated?date}
Last updated time: ${lastUpdated?time} 

will output something like:

Last updated: 04/25/2003 08:00:54 PM
Last updated date: 04/25/2003
Last updated time: 08:00:54 PM 

If the left side of the ? is string, then these built-ins convert strings to date variable .
iso_...
These built-ins convert a date, time or date-time value to string that follows ISO 8601 "extended"format. This built-in has several variations: iso_utc, iso_local, iso_utc_nz, iso_local_nz, iso_utc_m, iso_utc_m_nz, etc. The name is constructed from the following words in this order, each separated with a _ from the next:

iso (required)

Either utc or local (required (except when it's given with a parameter, but see that later)): Specifies whether you want to print the date according to UTC or according the current time zone. The current time zone is decided by the time_zone FreeMarker setting and is normally configured by the programmers outside the templates (but it can also be set in a template, like <#setting time_zone="America/New_York"> for example).

Either h or m or ms (optional): The accuracy of the time part. When omitted, it defaults to seconds accuracy (like 12:30:18). h means hours accuracy (like 12), m means minutes accuracy (12:30), and ms means milliseconds accuracy (12:30:18.25, where we have 250 ms). Note that when using ms, the milliseconds are displayed as fraction seconds (following the standard) and will not have trailing 0-s. Thus, if the the millisecond part happens to be 0, the whole fraction second part will be omitted. Also note that the fraction seconds are always separated with a dot , not with comma (to follow the Web conventions and the XML Schema date/time format).

nz (optional): When present, the time zone offset (like +02:00 or or -04:30 or Z) will not be displayed. Otherwise it will be displayed, except for date-only values (as dates with zone offset doesn't appear in ISO 8601:2004). Since FreeMarker 2.3.19, the offset always contains the minutes for XML Schema date/time format compliance.

Example:

<#assign aDateTime = .now>
<#assign aDate = aDateTime?date>
<#assign aTime = aDateTime?time>

Basic formats:
${aDate?iso_utc}
${aTime?iso_utc}
${aDateTime?iso_utc}

Different accuracies:
${aTime?iso_utc_ms}
${aDateTime?iso_utc_m}

Local time zone:
${aDateTime?iso_local} 

A possible output (depends on current time and time zone):

Basic formats:
2011-05-16
21:32:13Z
2011-05-16T21:32:13Z

Different accuracies:
21:32:13.868Z
2011-05-16T21:32Z

Local time zone:
2011-05-16T23:32:13+02:00 

There is yet another group of iso_... built-in variants, where you omit the local or utc word from the name and instead specify the time zone as a parameter to the built-in. Example:

<#assign aDateTime = .now>
${aDateTime?iso("UTC")}
${aDateTime?iso("GMT-02:30")}
${aDateTime?iso("Europe/Rome")}

The usual variations are supported:
${aDateTime?iso_m("GMT+02")}
${aDateTime?iso_m_nz("GMT+02")}
${aDateTime?iso_nz("GMT+02")} 

A possible output (depends on current time and time zone):

2011-05-16T21:43:58Z
2011-05-16T19:13:58-02:30
2011-05-16T23:43:58+02:00

The usual variations are supported:
2011-05-16T23:43+02:00
2011-05-16T23:43
2011-05-16T23:43:58 

If the time zone parameter can't be interpreted, the template processing will be terminated with error.
The parameter can be a java.util.TimeZone object too (which is possibly the return value of a Java method, or it's in the data-model), not just a string.