Timezones
Overview
By default the Eventcalendar uses the local timezone of the browser to show event data. If you want to show the data or interpret it in a different timezone, you will need an external library to handle the timezone conversions. There are three libraries that Mobiscroll supports: moment-timezone, luxon and Day.js.
When using a timezone plugin with the Eventcalendar, the exclusiveEndDates option defaults to true. Learn more about exclusive end dates!
Library Install
To setup the library, first you have to install it on your page. In this guide we'll assume you are using npm to install packages, but you can consult the installation guide on the libraries official pages (moment-timezone install page, luxon install page) for more options on how to install them.
The Moment-Timezone library
1. To install the moment-timezone library with npm you will need to run the following commands:
npm install moment-timezone
2. After the library is installed, you will have to import it with the momentTimezone object from mobiscroll:
import moment from 'moment-timezone';
import { momentTimezone } from '@mobiscroll/javascript';
3. Then set the mobiscroll's reference to the imported library:
import moment from 'moment-timezone';
import { momentTimezone } from '@mobiscroll/javascript';
momentTimezone.moment = moment;
4. After that, you can pass the momentTimezone object to the Eventcalendar's timezonePlugin option.
import { momentTimezone, eventcalendar } from '@mobiscroll/javascript';
import moment from 'moment-timezone';
momentTimezone.moment = moment;
eventcalendar('#myDiv', {
timezonePlugin: momentTimezone,
dataTimezone: "utc",
displayTimezone: "Europe/Berlin",
});
Moment in web pages
If you are not using any script bundler and you have the mobiscroll and moment library scripts included on your web page, you can access the momentTimezone from the mobiscroll global namespace.
mobiscroll.momentTimezone = moment;
mobiscroll.eventcalendar('#myDiv', {
timezonePlugin: mobiscroll.momentTimezone,
dataTimezone: "utc",
displayTimezone: "Europe/Berlin",
});
The Luxon library
1. To install the luxon library with npm you will need to run the following commands:
npm install luxon
In case you are using typescript you can also consider installing the types, because they come separately:
npm install --save-dev @types/luxon
2. After the library is installed, you will have to import it with the luxonTimezone object from mobiscroll:
import * as luxon from 'luxon';
import { luxonTimezone } from '@mobiscroll/javascript';
3. Then set the mobiscroll's reference to the imported library:
import * as luxon from 'luxon';
import { luxonTimezone } from '@mobiscroll/javascript';
luxonTimezone.luxon = luxon;
4. After that, you can pass the luxonTimezone object to the Eventcalendar's timezonePlugin option.
import { luxonTimezone, eventcalendar } from '@mobiscroll/javascript';
import * as luxon from 'luxon';
luxonTimezone.luxon = luxon;
eventcalendar('#myDiv', {
timezonePlugin: luxonTimezone,
dataTimezone: "utc",
displayTimezone: "Europe/Berlin",
});
Luxon in web pages
If you are not using any script bundler and you have the mobiscroll and luxon library scripts included on your web page, you can access the luxonTimezone from the mobiscroll global namespace.
mobiscroll.luxonTimezone = luxon;
mobiscroll.eventcalendar('#myDiv', {
timezonePlugin: mobiscroll.luxonTimezone,
dataTimezone: "utc",
displayTimezone: "Europe/Berlin",
});
The Day.js library
1. To install the Day.js library with npm you will need to run the following commands:
npm install dayjs
2. After installing the library, the utc and timezone plugins need to be included. You'll also need to import the dayjsTimezone plugin from mobiscroll:
import dayjs from 'dayjs';
import timezone from 'dayjs/plugin/timezone';
import utc from 'dayjs/plugin/utc';
import { dayjsTimezone } from '@mobiscroll/javascript';
dayjs.extend(utc);
dayjs.extend(timezone);
3. Then set the mobiscroll's reference to the imported library:
dayjsTimezone.dayjs = dayjs;
4. After that, you can pass the dayjsTimezone object to the Eventcalendar's timezonePlugin option.
import { eventcalendar, dayjsTimezone } from '@mobiscroll/javascript';
import dayjs from 'dayjs';
import timezone from 'dayjs/plugin/timezone';
import utc from 'dayjs/plugin/utc';
dayjs.extend(utc);
dayjs.extend(timezone);
dayjsTimezone.dayjs = dayjs;
eventcalendar('#myDiv', {
timezonePlugin: dayjsTimezone,
dataTimezone: "utc",
displayTimezone: "Europe/Berlin",
});
Day.js in web pages
If you are not using any script bundler and you have the mobiscroll and Day.js library scripts included on your web page, you can access the dayjsTimezone from the mobiscroll global namespace.
mobiscroll.dayjsTimezone = dayjs;
mobiscroll.eventcalendar('#myDiv', {
timezonePlugin: mobiscroll.dayjsTimezone,
dataTimezone: "utc",
displayTimezone: "Europe/Berlin",
});
Using timezones
When working with timezones, you usually have your data stored in one timezone, and display it in a different timezone. A common scenario is storing the data in UTC, and displaying it in the user's local timezone. You can set this using the dataTimezone and displayTimezone options.
You can also store the timezone inside the event data, using the timezone property. If an event has the timezone specified, this will take precedence over the timezone set by dataTimezone. This is particularly useful for recurring events. Storing recurring events in UTC is not useful in most of the cases, since the occurrences will be generated in UTC time, which does not have daylight saving times. When converted to a displayTimezone which uses DST, the event times will be shifted with an hour when DST changes. Storing the timezone on the event makes it unambiguous, and will be correctly converted to displayTimezone.
import { momentTimezone, eventcalendar } from "@mobiscroll/javascript";
import moment from 'moment-timezone';
// setup the reference to moment
momentTimezone.moment = moment;
eventcalendar('#myDiv', {
data: [],
timezonePlugin: momentTimezone,
dataTimezone: "utc",
displayTimezone: "Europe/Berlin",
});
Exclusive end dates
Exclusive end dates means that the last moment of a given range is not actually part of the range.
Many of existing calendaring solutions (e.g. Google Calendar) and standards (e.g. iCalendar) are working with exclusive end dates, so this makes interoperabiliy with our Eventcalendar UI simpler.
With the introduction of timezone support, this also became a necessity, e.g. if you have an event with start: '2021-07-09T20:00Z' and end: '2021-07-09T21:00Z', defined in UTC, when displayed in Europe/Bucharest timezone, the end becomes '2021-07-10T00:00+03:00'. With inclusive end dates the event will show up on 10th of July as well, which is unexpected.
The exclusive end dates mode can be enabled using the exclusiveEndDates option. When timezones are used (displayTimezone and/or dataTimezone is set), exclusive end dates are automatically enabled.
Enabling exclusive end dates can cause breaking changes, especially with all-day events with no time specified.
With inclusive end dates an event with start: '2021-07-09' and end: '2021-07-10' will show as a two day event on the calendar view, expanded over 9th and 10th of July. With exclusive end dates the event will be a single day event, showing up only on 9th of July.
