Built-ins for dates

• Built-ins for dates
• date, time, datetime (when used with a date value)
• isnull (when used with a date value)
• iso_...
• long
• string (when used with a date value)

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

expr?date

expr?time

expr?datetime

You can use these built-ins 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.

Due to technical limitations, RPL cannot always determine which parts of the date are in use. If RTL has to execute an operation where this information is needed, such as displaying the date as text, but cannot determine which parts are in use, it will produce an error that terminates template processing. In such cases, you have to use these built-ins.

The following example illustrates a potentially problematic variable, openingTime:

<#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 -->  

Additionally, you might use 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}  

produces this output:

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 a string, then these built-ins convert strings to date variables.

isnull (when used with a date value)

exp?isnull

This built-in is useful only for expressions representing fields from the database.

When a date field in the database is NULL, RPL converts it to a date representing January 1^st, 1800 in the current time zone, but the fact that this field came from a NULL value is temporarily retained. This built-in returns true if the date came from a NULL value, otherwise returns false. For non-database fields, the built-in always returns false. When an operation that involves a database field is performed (for instance adding a day with dayadd) the result does not retain whether it came from a NULL value from the database.

The default value for a NULL data field is January 1^st, 1800 in the current timezone of the template execution.

Example:

The following field in the database results in a NULL:

<#-- NULL is remembered -->

<#if profile.nulldate?isnull>

profile.nulldate is NULL

<#else>

profile.nulldate is NOT NULL

</#if>

<#-- 1800-01-01 00:00:00 is the default-->

${dayadd(profile.nulldate,1)?string("yyyy-MM-dd HH:mm:ss")}

<#-- the result is no longer null -->

<#if dayadd(profile.nullnumber,0)?isnull>

profile.nulldate+0 is NULL

<#else>

profile.nulldate+0 is NOT NULL

</#if>

produces this output:

profile.nulldate is NULL 

1800-01-02 00:00:00

profile.nulldate+0 is NOT NULL

iso_...

expr?iso…

Converts a date, time or date-time value to a string that follows ISO 8601 "extended" format. The name is constructed from the following words, in the order shown, separated by a _:

1. iso (required)

2. Either utc or local (required, except when used with parameters as described below).

   Specifies whether you want to print the date according to UTC or the current time zone. The current time zone is determined by the time_zone RPL setting and is normally configured by the system outside the templates. Note that the current time zone can also be set in a template, for example <#setting time_zone="America/New_York">.

   Omitting utc or local

   Instead of specifying utc or local, you can specify the time zone as a parameter.

   The parameter can also be a java.util.TimeZone object (which might be a return value of a Java method), or might be in the data-model.

   If RPL cannot interpret the time zone parameter, an error will occur that terminates template processing.

3. Either h, m, or ms (optional)

   The precision of the time part. When omitted, defaults to seconds (for example 12:30:18). h means hours precision (in this case 12), m means minutes precision (in this case, 12:30), and ms means milliseconds precision (in this case, 12:30:18.25, for 250 milliseconds). Note that when using ms, the milliseconds are displayed as a fraction of a second and trailing zeroes are omitted. This means that if the millisecond is 0, the millisecond will be omitted (for example, 12:30:18). The fraction is always separated with a dot to follow the Web conventions and the XML Schema date/time format.

4. nz (optional)

   When present, the time zone offset , such as +02:00 or -04:30 or Z, will not be displayed. Otherwise, the time zone offset will be displayed except for date-only values (because dates with zone offset does not appear in ISO 8601:2004). Since ITL 2.3.19, the offset always contains the minutes for XML Schema date/time format compliance. For 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}  

produces output similar to this, depending 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  

The following example illustrates the use of the built-in with utc or local omitted:

<#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")}  

produces output similar to this, depending 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  

long

expr?long

You can use this built-in with date, time and date-time values to get the number of milliseconds since January 1, 1970, 00:00:00 GMT (also known as the unix epoch date).

string (when used with a date value)

expr?string

expr?string.short

expr?string.medium

expr?string.long

expr?string.full

…

expr?string(mask-expr)

Converts a date to a string with the specified formatting.

Tip: You do need to use this built-in if you want to use the default format specified by the date_format, time_format, and datetime_format settings. 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. These formats 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, the following example:

${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}  

produces this output:

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 by the Java platform implementation on which you run RPL.

For dates that contain both a date and a time, you can specify the length of the date and time parts independently, as shown in the following example:

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

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

produces this 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: Due to technical limitations, in some cases RPL cannot determine whether the variable stores only date (year, month, day), only time (hour, minute, second, millisecond), or both. In such cases, RPL will stop with an error when you write something similar to ${lastUpdated?string.short} or  ${lastUpdated}. To prevent such errors, we recommend that you always use the ?date, ?time, and ?datetime built-ins, for example: ${lastUpdated?datetime?string.short}.

Instead of using the predefined formats, you can specify the formatting pattern explicitly with ?string(pattern_string). The pattern uses the Java date format syntax explained in the “About the date format” section. For 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')'")}  

produces this output:

2003-04-08 21:24:44 Pacific Daylight Time

Tue, Apr 8, '03

Tuesday, April 08, 2003, 09:24:44 PM (PDT)  

NOTE: With explicitly given patterns, you do not need to use ?date, ?time, and ?datetime. This is because the pattern specifies which parts of the date to show. However, note that you can show "noise" if you display parts that are 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 using the predefined formats with the dot syntax: someDate?string("short") and someDate?string.short are equivalent.