FreeMarker Manual - Built-ins for dates

Built-ins for dates

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.

date, time, datetime

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.


Page generated: 2008-08-31 23:11:23 GMT	FreeMarker Manual -- For FreeMarker 2.3.14