Advanced Techniques - Velocity date API
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 that 0 means January, 1 is 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()))
In a call, the incorrect value 0 April 2018 would deliver 31.03.2018 as the result.
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 amount of parameters. In this way, a date
can be generated that only specifies the required year, 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 Intrexx
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.
These include various public holiday calculations, the parsing of date
literals, and date comparisons. Please refer to the Java documentation
for the DateTimeUtil and CalendarAwareDate classes.