Built-ins for dates
Page Contents
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:
![]() | ![]() | ![]() | |
![]() |
| ![]() | |
![]() | ![]() | ![]() |
will prints something like this:
![]() | ![]() | ![]() | |
![]() |
| ![]() | |
![]() | ![]() | ![]() |
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:
![]() | ![]() | ![]() | |
![]() |
| ![]() | |
![]() | ![]() | ![]() |
will output:
![]() | ![]() | ![]() | |
![]() |
| ![]() | |
![]() | ![]() | ![]() |
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:
![]() | ![]() | ![]() | |
![]() |
| ![]() | |
![]() | ![]() | ![]() |
will output:
![]() | ![]() | ![]() | |
![]() |
| ![]() | |
![]() | ![]() | ![]() |
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
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:
![]() | ![]() | ![]() | |
![]() |
| ![]() | |
![]() | ![]() | ![]() |
There is another usage of these built-ins: to truncate dates. For example:
![]() | ![]() | ![]() | |
![]() |
| ![]() | |
![]() | ![]() | ![]() |
will output something like:
![]() | ![]() | ![]() | |
![]() |
| ![]() | |
![]() | ![]() | ![]() |
If the left side of the ? is string, then these built-ins convert strings to date variable.