dateCalc (Calculate date)


The function $dateCalc calculates datetime values by applying absolute and relative calculation components to a reference date value or current system time.

Syntax

$dateCalc(expression[,dateValue])

Parameter

Name

Description

expression

An expression with one or more calculation components, which are applied to a reference date defined by the 'Date value' parameter (see below).

Each calculation component uses the following structure:

[+|-]NU

... where N represents an integer number and U (unit) is a single character which identifies a specific date component (e.g. M for month; see dedicated section below for complete mapping):

  • Unsigned calculation components define an absolute value for the indicated component (U), defined by the integer number (N).

  • Signed calculation components (with a prefix of '+' or '-') define an offset of (N) units of the indicated component (U) which are added or subtracted to the component value of the reference date (see Date value) or an intermediate result derived from it.

Multiple calculation components can be concatenated via blank characters separately. They are processed sequentially (from left to right).

Example: '+1d +3h 0m' = Add one day, add one hour and set minutes to zero.

►NOTE◄

  • Interpretation logic for the 'expression' largely matches the definitions described for resolvers Relative date with time and Relative date range with time, however – as pointed out in the table below – not all date components are supported in $dateCalc expressions.

  • Besides static text provided in the function call, the 'expression' parameter also accepts text returned by other functions, so expressions can be assembled dynamically, if necessary.

dateValue
(optional)

This optional parameter defines the reference time for the date determination. If not specified, the current client time ($now() ) serves as the reference time.

Date values accept assigned values of the following types:

  • Date time

  • Date range (combination of two 'from/to' date time values. The 'from' date will be used as reference date(time))

  • Time

  • Timestamp

  • Date (Javascript date)

  • Long (Unix timestamp indicating a number of milliseconds)

Return value

Returns the result of the calcuation as a new value which is compatible to the input value (dateValue parameter). If dateValue is a date range object (DateRange), for example, the output value will also be a date range object.

Code characters representing date components

The following code letters are permitted for identifying date components in the expression parameter:

Code letter

Date component

Permitted values

y

year

>= 1

M

month of the year

1 (January) ... 12 (December)

d

day of the month

1 ... number of days in the specified month

D

day of the year

1 ... number of days in the specified year

w

week of the year

not supported by the client

F / E

day of the week

not supported by the client

H

hour of the day

0 ... 23

m

minute of the hour

0 ... 59

s

second of the minute

0 ... 59

S

milliseconds of the second

0 ... 999

Examples

1. Absolute date value built from components

An absolute date value (February 16, 2015 01:21 PM) is defined by the following function call:

  • $dateCalc(16d 2M 2015y 13H 21m 0s 0S)

►NOTE◄ Without calculation components '0s 0S' included in the expression, the value for seconds and milliseconds would be determined by the current system time.

2. Relative date time 'This time tomorrow'

The following function call determines a date time relative to the current system time by combining the following calendar day with the current time value:

  • $dateCalc(+1d)

3. Relative date time '5 pm on the last day of the month of a given date value'

The following function call combines absolute and relative calculation components to a reference date of a certain field (with ID # 99):

  • $dateCalc(1d +1M -1d 17H 0m 0s 0S, $el(99))

4. Relative date time depending on input/selection in other fields

The following function call determines a date time relative to the current system time and involves input/choices in other fields:

  • $dateCalc($concatWs(+,$el(12),d ,$el(14), 0s 0S))

An input field with ID # 12 defines a certain number of days as an offset into the future. A combobox with ID # 14 defines absolute time components with two alternative values '10H 0m' and '17H 45m'.

images/download/attachments/62864259/image2019-10-22_17-58-39-version-1-modificationdate-1610960112662-api-v2.png

  • In this form the 'Delivery date (calc.)' is determined by $dateCalc considering read-only field 'Lead time' (element # 12) - applied relative to current system date time - in combination with a user choice for delivery time ('Delivery until ...', element # 14).

  • 'Delivery date (calc).' is updated by a Calculate behaviour triggered upon change of the choice for 'Delivery until ...'.

Hint: $dateCalc in expressions for comparing date values

$dateCalc can be used in expressions for comparing date values in behaviours (Compare with (Form designer)) or validators of date fields (Compare to (Validator)).

Example: Maximum timespan between 'from' and 'to' date of a date range

A Date range should be equipped with a validator to ensure a maximum timespan of 3 months between indication for 'from' and 'to' date.

Configuration

images/download/attachments/62864259/dateCalcConfig-version-1-modificationdate-1610960112611-api-v2.png

  • In the 'Validators' section of the properties of the 'to' element of a date range element a Validators of type Compare to (Validator) is added.

  • Compare type is defined as 'Less or equal', since the date value determined by $dateCalc should be the maximum acceptable date.

  • Compare source is set to the option Expression, so a Calculation expression can be entered.

  • The Calculation expression uses $dateCalc to determin the latest acceptable date relative to the 'from' date (element with ID # 7):

    • The Expression parameter +3M adds three months to the value of the Date value parameter.

    • The Date value parameter receives the value of field # 7 ('from' date).

Application example

Invalid input:

images/download/attachments/62864259/image2019-10-22_15-25-34-version-1-modificationdate-1610960112653-api-v2.png

Valid input:

images/download/attachments/62864259/image2019-10-22_15-26-18-version-1-modificationdate-1610960112648-api-v2.png

►NOTE◄

  • The date values used in this example were picked to illustrate, that the $dateCalc function call ('11/30/2019' +3M) determines 03/01/2020 as the maximum acceptable 'To' date, as opposed to '02/30/2020' which would be an invalid date, even in a leap year.

  • Both date elements should use the option Time 00:00 on date change in property-section 'Date/Time'. Otherwise, the system time could be attached to date selections causing misinterpretations by the validator, which considers any time component visible or not.

    images/download/attachments/62864259/image2019-10-22_15-31-4-version-1-modificationdate-1610960112645-api-v2.png

  • Changing the 'From' date does not automatically update the validation status of the 'To' element. If required, a Validate element action for the 'To' element can be triggered upon change of the 'From' element.