v7.3.0

Time zone support

As of version 5.3.0 there is built-in support for time zone conversions in all Bryntum scheduling products. This means that a Scheduler, for example, can be configured to a different time zone and show time as it is in configured time zone.

Configuring

Set projects timeZone config to a IANA time zone (i.e. Europe/Stockholm) or a UTC offset in minutes (i.e. -120). This will convert all events, tasks and time ranges to the configured time zone or offset. It will also affect the displayed timeline's headers as well at the start and end date of it.

 new Scheduler({
    project : {
        // This will convert time to CET (UTC+1) or
        // CEST (UTC+2) depending on DST 
        timeZone : 'Europe/Stockholm'
    }
});

There is also a referer timeZone config available on the Scheduler, SchedulerPro, Gantt and Calendar. This will set/get the timeZone config on the components project. Please note that if switching to a new project, the timeZone configuration will need to be reset.

 new Scheduler({
    // This will convert time to CST (UTC-6) or
    // CDT (UTC-5) depending on DST
    timeZone : 'America/Chicago'
});

Specifying a UTC offset in minutes is also possible. The provided number has no built-in limitations. The amount of minutes relative to UTC will simply be added or subtracted from the date that is being converted. Please note that this approach has no DST support at all.

new Scheduler({
    // This will convert dates to UTC and 
    // then subracting 12 hours from them.
    timeZone : -60 * 12
});

Data

The events, tasks and time ranges that are loaded or being loaded into the project will be put through a time zone conversion function.

  • A provided JavaScript Date will be interpreted as local to the client's system time zone. Please read the section about JavaScript Dates below.
  • A provided string Date will be interpreted by JavaScript to a local Date and then converted to the configured time zone. Examples of different string dates:
    • 2022-10-26T14:28:01 - A date local to the client's system time zone.
    • 2022-12-24T14:00:00Z - A UTC date
    • 2022-12-31T23:59:59+01:00 - A date in UTC+1 time zone
Dates on events, tasks and time ranges that is added or inserted to a store will be treated as already *in* the currently configured time zone. This means that no time zone conversion will be applied when adding or inserting records, unless you set the `timeZone` field on the record before adding it to the Store. Set it either to another IANA time zone or `null` to apply time zone conversion to the added record.

Editing

After the Scheduler has been converted to a different time zone, editing or creating a record will be interpreted as in the configured time zone. This also includes programmatically created records. There will therefore be no time zone conversion on created or updated record's dates.

Saving

When saving or syncing data, the dates will be restored to local system time and converted to JSON, in ISO format.

JavaScript Dates

There is currently no native support for time zones in JavaScript. A JavaScript Date is in the client's system time zone and also holds information about its UTC equivalent at that particular point in time. That means that a time zone converted time technically is in the client's system time zone, but adjusted to match the configured time zone.

Daylight Saving Time (DST)

When using a IANA time zone identifier there will be support for DST. But due to the fact that a JavaScript date is in the client's system time zone, there are cases when the conversion gives a faulty result. These cases occur when the client's system time zone has DST and the converted result date is exactly at the hour when DST adds an hour.

Example: Convert date time in UTC+1 to Antarctica/Casey (UTC without any DST):

TimeZoneHelper.toTimeZone(new Date('2022-03-27T03:00+01:00'), 'Antarctica/Casey');

This should return 2022-03-27T02:00.

But when client's system time zone is Europe/Stockholm it returns 2022-03-27T03:00 instead, due to that Europe/Stockholm enters DST at 2022-03-27T02:00 and therefore skips that hour.

TimeZoneHelper

The TimeZoneHelper is available for time zone conversion. It holds only 2 functions, toTimeZone and fromTimeZone.

What time is it now in Asia/Nicosia?

TimeZoneHelper.toTimeZone(new Date(), 'Asia/Nicosia');

What is this date in client's system time zone if current time zone is Atlantic/Reykjavik?

TimeZoneHelper.fromTimeZone(new Date('2022-02-06T12:00'), 'Atlantic/Reykjavik');

Contents