# Date Handling
# Introduction
Date blocks are used as input parameters for other blocks or can be used to create or compare date. With 3.3.0M6 many blocks were introduced to allow complex tasks with dates
- Introduction
- Overview of the Date Handling blocks
- Date Handling Blocks
- Help
- Get Datetime now
- Get Datetime now with offset
- Date-picker
- Get date
- Datetime with date and time values
- Create Datetime based on a specific date ("Copy Of")
- Datetime from item
- Get String representation of date ("text of")
- Date Comparison
- Date Comparison Between
- Get part of datetime
- Get difference between datetimes
- today (ephemeris block)
- today +/- x days (ephemeris block)
- Return to Blockly Reference
# Overview of the Date Handling blocks
Note: There is no need for a special block to set a datetime of an openHAB item. This can be directly done via the "send command" / "post command" block
# Date Handling Blocks
More about that topic can be viewed at 
Datetimes and Cron-Triggers (opens new window)
# Help
Type: Link to openHAB documentation
This button serves as a link to this documention page
# Get Datetime now
Type: ZonedDateTime
Obtains the current datetime from the system clock in the default timezone as ZonedDateTime
# Get Datetime now with offset
Type: ZonedDateTime
Obtains the current datetime as ZonedDateTime with an offset relative to the current date and time.
The options for the time period base are
- seconds
- minutes
- hours
- days
- months
- years
# Date-picker
Type: ZonedDateTime
Returns a date as ZonedDateTime.
The date can be selected from a date picker.
The time is set to 00:00:00.
# Get date
Type: ZonedDateTime
This block will return the date as ZonedDateTime based on the given String. The String may be one of the following formats (since 3.3) the following formats are supported)
- HH:mm
- HH:mm:ss
- yyyy-MM-dd
- yyyy-MM-dd HH:mm
- yyyy-MM-dd HH:mm:ss
- yyyy-MM-dd HH:mm:ss +HH:mm
- yyyy-MM-dd HH:mm:ss.SSS
- yyyy-MM-dd HH:mm:ss.SSSSS
- yyyy-MM-dd HH:mm:ss.SSS+HH:mm
- yyyy-MM-dd HH:mm:ss.SSSSSS+HH:mm (local date time standard output)
- yyyy-MM-dd HH:mm:ss.SS+HHmm (OH standard output format)
The input String may also be provided via variable-block or a date from an item state. In case parts of the date are not provided due to shorter pattern, the others are set to 0
TIP
if you want to create a datetime with your time zone use the "copy of"-block and overwrite its values
More about that topic can be viewed at Creating Datetimes and other datetime blocks (opens new window)
# Datetime with date and time values
Type: ZonedDateTime
Creates a ZonedDateTime by providing all necessary six values
- year of day
- month of day
- day
- hour of time
- minute of time
- second of time
TIP
if you want to create a datetime with your time zone use the "copy of"-block and overwrite its values
# Create Datetime based on a specific date ("Copy Of")
since 3.3
More about that topic can be viewed at Copy-Of, Datetime-Now with Math-Operations (opens new window)
Type: ZonedDateTime
This block allows to create a new ZonedDateTime based on a given ZonedDateTime and then either
- overwrites
- adds
- or subtracts
Temporals: parts of that datetime are called temporals
More about that topic can be viewed at Datetime - Temporal Units (opens new window)
It is therefore a bit more complex block which is on the other hand very flexible to use. It consists of the main "copy of"-block and the other two temporal-Blocks that can be added.
The following short video explains how the block can be used
- first drag the main copyOf-Block to the workspace
- choose the datetime you want to base your new datetime on and drag it into the position (in the above video the now block is used)
- select if you want to set (overwrite), add or subtract values via the dropdown
- open the settings icon and drag as many "temporal units" into the block as you want to modify later, which will create the "holes" into which you can apply the temporal blocks
- now drag one of the temporal blocks (see description below) in each of these blocks. Note that these can be mixed
- Select the temporal unit by clicking on the arrow of that blocks which allows you to choose from one of the following
- year
- month
- day
- hour
- minute
- second
- milli
- micro
- nano
- day of year
- Modify the values of the temporal unit blocks
The two different temporal unit blocks
There are two different blocks that can be dragged into the main block which have both advantages and disadvantages.
The dense and simple temporal block
This is the more dense block which is very suitable to create a "lightweight" block itself like so:
You can achieve the exact same result with the following but it looks more bulky and bit more complicated:
The bulky but powerful temporal block
This block also provides a temporal value to the main block but it contains an additional indirection for the value of the temporal block. While the first block only takes a constant, this block allows and even requires the value to be provided by another block which in the standard case is a number block.
Using just the number would be the same like providing a constant value but instead, any number-returning block can be used, hence any math operation can be applied like depicted into following image:
The main power arrives when using variables, which allows to calculate values that should be applied to the datetime.
In the following two values are retrieved from items, added and assigned to a variable. This variable is then used as the value to amend the lastUpdatedTime of an item which is posted to the target item to be processed.
# Datetime from item
since 3.3
Type: ZonedDateTime
This is a convenience block that retrieves the state of an item (at best of item type datetime) which is then automatically converted to a ZonedDateTime, so it can be easily used as shown in the following example:
More about that topic can be viewed at Convert item states to Datetimes (opens new window)
# Get String representation of date ("text of")
Type: String
Returns the String representation of a given ZonedDateTime-block, with, without the time or formatted in openHAB time (like in the logs). It also allows to return the date in a custom format which can be provided in a separate block.
since 3.3: also returns the same datetime format that is used by openHAB itself
Example
Assuming this block is run at 20:47:36 on 31/01/2022
The output in the log will be.
2022-01-31
2022-01-31 00:00:00
2022-01-31 20:47:36
# Date Comparison
since 3.3
An introduction to that topic can be viewed at Date comparison (opens new window)
Checks if the instant of the first ZonedDateTime is before, after or equal to the second ZonedDateTime. In the third drop-down list, the accuracy on which the comparison is based can be selected.
Type: boolean
Returns true/false based on the comparison
# Date Comparison Between
since 3.3
Check if the instant of the first datetime is between the two other datetimes. The drop-down decides if all components, date only or time only should be used for the comparison.
Type: boolean
Returns true/false based on the comparison
# Get part of datetime
since 3.3
Type: Number
Returns the selected part of the datetime as a number.
# Get difference between datetimes
since 3.3
Calculates the amount of time between two datetimes. The result will be negative if the second object is before the first one.
Type: Number
Returns the difference between the two datetimes.
# today (ephemeris block)
Type: DayOffset
Ephemeris blocks expect a date formatted as the number of days since today. As a result, this block always returns 0. Used for Emphemeris blocks only.
# today +/- x days (ephemeris block)
Type: DayOffset
Returns the number of days since today, as configured in the number block. The number can be positive (offset into the future) or negative (offset into the past). Used for Emphemeris blocks only.