In this workshop, we will demonstrate how date calculations can be executed quickly and simply in Intrexx using Velocity. Intrexx provides the object "$DtUtil" for such purposes. 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.
You can find the complete Java API documentation here.
Date values can be generated with "$DtUtil". 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 lead to exceptions. Example:
#set($date = $DtUtil.date(2018,3,0,$User.getTimeZone()))
The incorrect value 0 in the call. April 2018 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. The "date()" method used can be called with a different number of parameters. In this way, a date can be created in which only the desired year is specified and the remaining values such as month, day, etc. are set to initial values (01. January, fair values are set to 0). Alternatively, "date()" can be called, for example, with all parameters that can be set, from the 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 on which the date is based. 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, for example, date values are to be displayed or calculated, the respective time zone of the viewer must be taken into account in order to ensure an error-free display.
If several date operations with time zones take place on a page or within a script, it makes sense to define an auxiliary 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 created via "$DtUtil", you will receive an object of the "CalendarAwareDate" class as a return.
The class derives from "java.sql.Timestamp" and therefore also from "java.util.Date" and "IDateTimeValueHolder", i.e. all the methods available there can also be applied to "CalendarAwareDate" objects.
It can be seen from the Java documentation that there is an analogous method with the suffix "R" for each method, 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 datum to which the method was applied, but use the return type "void". 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 shown above, there are various methods for calculating dates 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
With "$DtUtil" it is also possible to prepare date literals so that they can then be transferred to a JavaScript function and further client-side calculations can be carried out. 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"), insert the GUID of a text field (static text) in which the prepared ISO date from Velocity is located.
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.
Send us an e-mail