In this workshop, we will demonstrate how date calculations can be executed quickly and simply in Intrexx using Velocity. Intrexx provides the $DtUtil object for this purpose. We will show you some use cases and sample calculations in this workshop. Background knowledge in Veloctiy, JavaScript and Java are an advantage for this workshop.
The complete Java API documentation can be found here.
With $DtUtil, date values can be generated. These include the current date, date values with specific adjustments for the year, month, day etc., as well as parsing of date values from strings or specific public holidays such as Good Friday. The numbering of the months starts with 0, as is usual in Java and JavaScript. This means: 0 specifies January, 1 specifies February, etc. The API uses lenient calendars, i.e. overflows or underflows of date fields (month, day, hour, minute, second, millisecond) do not cause exceptions. Example:
#set($date = $DtUtil.date(2018,3,0,$User.getTimeZone()))The incorrect value 0 April 2018 in the call leads to the result 31.03.2018.
Generate current date
Generates the current date based on the transferred time zone, in this case, that of the user currently logged in to the portal:
#set($now = $DtUtil.now($User.getTimeZone()))Generate any date
Generates any date based on the transferred time zone. Generate any date Generates any date based on the transferred time zone. This means a date can be created where only the desired year is specified and the remaining values such as month, day, etc. are set to their initial values (01 January, time values to 0). Alternatively, date() can be called, for example, with all configurable parameters ranging from year to milliseconds. More details can be found in the Java documentation.
New date with a specification of the 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 with a specification of the 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 point in date calculations is the time zone as the basis for the date. An Intrexx environment may contain multiple time zones. The basis is the time zone of the server that the portal service runs on. In certain circumstances, there may be a separate time zone for database operations. This depends on the configuration of the database in use. Futhermore, individual Intrexx users may have personal time zone settings assigned. To what extent the time zone plays a role in date operations depends on the specific use case and cannot be generalized. An example of a use case is to store the current timestamp in the database. In this case, the inclusion of the time zone is not absolutely essential. However, if date values are to be displayed or calculated, for example, the time zone of the viewer must be taken into account to ensure that dates are presented correctly. If there are several date operations including time zones on a page or in a script, it is useful to define an auxiliary variable $tz at the beginning of the script, and to assign the time zones that are to be used to this variable.
#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 via $DtUtil, an object from the CalendarAwareDate class is returned. The class is derived from java.sql.Timestamp and thus also from java.util.Date and from IDateTimeValueHolder, so that all of the methods available there are also usable for CalendarAwareDate objects. As the Java documentation states, there is a similar method for each method but with the suffix R such as addDays(int p_iDays) and addDaysR(int p_iDays). The methods differ in their respective return values. The methods without the R suffix do not return the date that the method was applied on but they use the void return type. For methods with the suffix, the object itself is returned. In this way, combinations of method calls are possible, meaning that help variables do no need to be defined and an undesirable inflation of the code can be prevented in doing so.
#set($dtNow = $DtUtil.now($User.getTimeZone()))
$dtNow.addYears(1)
$dtNow.addMonths(6)
$dtNow.addDays(10)
#set($dtNew = $dtNow)
With R suffix:
#set($now = $DtUtil.now($User.getTimeZone()))
#set($dtNew = $now.addYearsR(1).addMonthsR(6).addDaysR(10))
Date calculations
As was shown in the previous chapter, there are various methods for date calculations, such as addition and subtraction, for CalendarAwareDate objects. Analogous methods for addition and subtraction are available for all date properties (year, month, etc.). In addition to the previously described methods with the R-suffix, there are also methods where the UTC time zone is part of the name. To add a certain number of years, the following methods are available:
-
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 a return 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 manipulated object as a return value.
addUTCYears(int p_iYears)
Adds p_i Years to an existing date in the UTC time zone without a return value.
addUTCYearsR(int p_iYears)
Adds p_i Years to an existing date in the UTC time zone and returns the manipulated object as a return value.
Date literals for JavaScript
Using $DtUtil it is also possible to prepare date literals so that they can be transferred to a JavaScript function forfurther client-side calculations. With the Velocity script
#set($date = $DtUtil.now($User.getTimeZone()))
$DtUtil.dateToISOString($date)
the current date can be treated as an ISO string for JavaScript (ECMAScript Language Specification) and then used in JavaScript, as shown in the following script. In the call getElement("GUID"), the GUID of the text field (static text), which contains the processed ISO date from Velocity, should be inserted.
function alertJsDate()
{
var dtNowJS = Browser.getValue(getElement("9661....3FA9"));
alert(new Date(dtNowJS));
return true;
}
Additional methods
In addition to the methods described in the previous chapters, there are numerous other methods that can assist in the implementation of other use cases. Please refer to the Java documentation for the DateTimeUtil and CalendarAwareDate classes.
Email us