This post shows how date calculations can be performed quickly and easily in Intrexx using Velocity. Intrexx provides the "$DtUtil" object for this purpose. Here, we'll show you a few use cases and sample calculations. Prior knowledge of Velocity, JavaScript, and Java is helpful for this post.
You can find the complete Java API documentation here.
"$DtUtil" can be used to generate date values. This includes the current date, date values with specific adjustments for year, month, day, etc., as well as parsing date values from strings or holiday-specific dates such as Good Friday. As is customary in Java and JavaScript, the month count starts at 0. This means: 0 specifies January, 1 specifies February, and so on. The API uses lenient calendars, which means that overflows or underflows in date fields (month, day, hour, minute, second, millisecond) do not result in exceptions. Example:
#set($date = $DtUtil.date(2018,3,0,$User.getTimeZone()))
The value 0, which is incorrect in the call. April 2018 results in the date March 31, 2018.
Generate the current date
Generating the current date based on the specified time zone; in this example, using the time zone of the user currently logged in to the portal:
#set($now = $DtUtil.now($User.getTimeZone()))
Generate a random date
Generate any date based on the specified time zone. The "date()" function can be called with a varying number of parameters. This allows you to generate a date by specifying only the desired year, with the remaining values—such as month, day, etc.—set to their default values (01. January, values are set to 0. Alternatively, "date()" can be called with all configurable parameters, ranging from the year down to milliseconds. For more details, refer to the Java documentation.
New date, specifying the desired year:
#set($date = $DtUtil.date(2000, $User.getTimeZone()))
The result is a new date object with the value "2000-01-01 00:00:00.0". New date, including year, month, day, and hour:
#set($date = $DtUtil.date(2012, 1, 29, 18, $User.getTimeZone()))
The result is a new date object with the value "2012-02-29 18:00:00.0".
Time Zones
An important consideration in date calculations is the time zone on which the date is based. In the Intrexx environment, you may encounter different time zones. The basis is the time zone of the server on which the portal service is running. For database operations, there may be a separate database time zone under certain circumstances. This depends on the configuration of the database being used.
In addition, individual Intrexx users can be assigned personal time zone settings. The extent to which the time zone plays a role in date operations depends on the specific use case and cannot be generalized. One use case, for example, is to save the current timestamp to the database. In this case, it is not mandatory to specify the time zone. However, if, for example, date values are to be displayed or calculated, the viewer's time zone must be taken into account to ensure accurate display.
If multiple date operations involving time zones occur on a single page or within a script, it is a good idea to define a helper variable "$tz" at the beginning of the script and assign the time zone to be used to it.
#set($tz = $User.getTimeZone())
#set($dtDate1 = $DtUtil.date(2000, $tz))
#set($dtDate2 = $DtUtil.date(2001, 8, $tz))
CalendarAwareDate and R method suffixes
If a new date is generated using "$DtUtil," the function returns an object of the "CalendarAwareDate" class.
The class extends "java.sql.Timestamp" and, consequently, also "java.util.Date" and "IDateTimeValueHolder"; that is, all methods available in those classes can also be applied to "CalendarAwareDate" objects.
According to the Java documentation, for every method there is a corresponding method with the suffix "R," for example, "addDays(int p_iDays)" and "addDaysR(int p_iDays)."
The methods differ in their respective return values. Methods without an "R" suffix do not return the date on which the method was applied; instead, they use the "void" return type. For methods with a suffix, the object itself is returned. This allows for chained method calls, which can eliminate the need to define auxiliary variables and thus prevent the code from becoming bloated.
#set($dtNow = $DtUtil.now($User.getTimeZone()))
$dtNow.addYears(1)
$dtNow.addMonths(6)
$dtNow.addDays(10)
#set($dtNew = $dtNow)
With an "R" suffix:
#set($now = $DtUtil.now($User.getTimeZone()))
#set($dtNew = $now.addYearsR(1).addMonthsR(6).addDaysR(10))
Date Calculations
As shown earlier, "CalendarAwareDate" objects have various methods for date calculations, such as addition and subtraction. There are corresponding methods for addition and subtraction for all date properties (year, month, etc.). In addition to the methods described earlier that end with an "R" suffix, there are also methods in which the time zone (UTC) is part of the name. For adding a number of years, the following methods are available, for example:
-
addYears(int p_iYears)
-
addYearsR(int p_iYears)
-
addUTCYears(int p_iYears)
-
addUTCYearsR(int p_iYears)
Explanation:
addYears(int p_iYears)
Adds p_iYears years to an existing date, taking into account the time zone of the existing date, without returning a value.
addYearsR(int p_iYears)
Adds p_iYears to an existing date, taking into account the time zone of the existing date, and returns the modified object as the return value.
addUTCYears(int p_iYears)
Adds p_iYears to an existing date in the UTC time zone without returning a value.
addUTCYearsR(int p_iYears)
Adds p_iYears to an existing date in the UTC time zone and returns the modified object.
Date Literals for JavaScript
Using "$DtUtil," it is also possible to format date literals so that they can then be passed to a JavaScript function, allowing for further client-side calculations. Using the Velocity script
#set($date = $DtUtil.now($User.getTimeZone()))
$DtUtil.dateToISOString($date)
The current date can be formatted as an ISO string for JavaScript (according to the ECMAScript Language Specification) and then used in JavaScript, as shown in the following script. In the call `getElement("GUID")`, insert the GUID of a text field (static text) that contains the formatted ISO date from Velocity.
function alertJsDate()
{
var dtNowJS = Browser.getValue(getElement("9661....3FA9"));
alert(new Date(dtNowJS));
return true;
}
Other Methods
In addition to the methods described here, there are numerous other methods that can help with implementing other use cases, such as holiday calculations, parsing date literals, and date comparisons. For more information, refer to the Java documentation for the "DateTimeUtil" and "CalendarAwareDate" classes.