Upgrading to v2
FullCalendar version 2.0 (full documentation) offers huge improvements in regards to timezones, internationalization, and date manipulation. Much of this is due to intergration with MomentJS, which is now a dependency. Because the changes are so dramatic, compatibility with the 1.x versions has been broken. This guide explains the differences between versions.
Options that now use Moments
Instead of native Date objects, Moment objects are now used throughout the API.
In addition, all end dates are now exclusive. For example, if an all-day event ends on a Thursday, the end date will be 00:00:00 on Friday.
The 1.x versions had some strange rules in regards to this. Things should be much simpler
now that exclusive end dates are used consistently throughout the API.
In addition, this behavior is more consistent with other API’s and formats,
such as iCalendar.
Affected options:
| Option | Upgrade Notes |
|---|---|
year | use defaultDate instead, which is Moment-like and determines year, month, and date |
month | |
date | |
gotoDate method | Uses Moments |
getDate method | |
events as a function | |
dayRender callback | |
dayClick callback | Uses Moments, which may be ambiguously-timed.allDay removed, delta added |
drop callback | |
eventDrop callback | Uses Moments, which may be ambiguously-timed.allDay removed, delta added |
eventResize callback | |
select callback | Uses Moments, which may be ambiguously-timed.allDay parameter removed. end is now exclusive! |
select method |
Event Object modifications:
| Property | Upgrade Notes |
|---|---|
.start | is now a Moment |
.end | is now a Moment, and is always exclusive! |
View Objects modifications:
| Property | Upgrade Notes |
|---|---|
.visStart | has become .start (a Moment) |
.start repurposed! | has become .intervalStart (a Moment) |
.visEnd | has become .end (an exclusive Moment) |
.end repurposed! | has become .intervalEnd (an exclusive Moment) |
Note: anywhere in the API that accepts a Moment parameter, a “Moment-like” parameter (anything
the Moment constructor accepts) can also be given.
This includes raw ISO8601 strings like "2013-12-25".
Options that now use Durations
The MomentJS library provides a Duration object, which is also used throughout the API. It is used to specify intervals of time and anonymous times. The following options have been affected:
| Option | Upgrade Notes |
|---|---|
incrementDate method | accepts a Duration |
slotMinutes | superseded by slotDuration |
snapMinutes | superseded by snapDuration |
firstHour | superseded by scrollTime |
defaultEventMinutes | superseded by defaultTimedEventDuration |
superseded by defaultAllDayEventDuration |
Note: Anywhere the API accepts a Duration, a “Duration-like” parameter can be given (anything the
Duration constructor accepts).
This includes raw strings like "02:00" (two hours).
Date Formatting and Parsing
FullCalendar now leverges MomentJS for formatting dates into strings. Many of the formatting characters are the same, but some have changed!
| Old Characters | New Characters |
|---|---|
yyyy (4 digit year) | YYYY |
yy (2 digit year) | YY |
dd (2 digit date of month) | DD |
d (1 digit date of month) | D |
tt (am or pm) | a |
TT (AM or PM) | A |
S (st, nd, rd, th) | o |
'' (escape characters) | [] |
[] and {} for range formatting | no replacement. formatRange works differently |
u (outputs IS08601) | use moment's toISOString instead |
See the MomentJS formatting characters for the full list of available characters.
Additionally, there are some FullCalendar-specific formatting characters,
such as t, T, and ( ).
The following date utility methods have also been affected:
| Method | Upgrade Notes |
|---|---|
$.fullCalendar.parseDate | use a moment constructor |
$.fullCalendar.parseISO8601 | |
$.fullCalendar.formatDate | use a moment's .format() method instead |
$.fullCalendar.formatDates | use $.fullCalendar.formatRange instead |
Internationalization
The new lang option provides built-in support for over 40 locales!
Changing the locale affects the default values of many options
(such as isRTL and dayNames).
However, these options can still be individually overridden if need be.
Other affected locale-related options:
| Option | Upgrade Notes |
|---|---|
weekNumberCalculation | new "local" option, which is now the default |
Timezones
The new timezone option provides flexible support for arbitrary
timezones! The potential values are:
false- no timezone (default)"local"- the timezone of the browser"UTC"- a specific timezone string like
"America/Chicago"
Certain existing options were modified for timezone support:
| Option | Upgrade Notes |
|---|---|
events as a function | Receives a timezone parameter.Changes the argument order for callback! |
events as a JSON feed | Might send a timezone parameter in the request |
ignoreTimezone | Was a bad idea in the first place |
currentTimezone(Google Calendar plugin option) | Uses the calendar's timezone option instead |
The
timezoneParam and
now
options have been added as well.
Requesting and Receiving Events
| Option | Upgrade Notes |
|---|---|
events as a function | Receives a timezone parameter.Changes the argument order for callback! |
events as a JSON feed | Sends ISO8601 dates for start and end |
allDayDefault | Defaults to undefined instead of true to allow for the smart allDay guessing behavior... |
When an Event Object’s allDay property is not specified,
FullCalendar is now smarter about guessing it.
If either the start or end value has a “T” as part of the ISO8601 date string,
allDay will become false. Otherwise, it will be true.
forceEventDuration has been added.
When true, it will ensure that any event inputted with an empty end date will have that
date computed via defaults instead of allowing it to remain null.
Other API Changes
| Option | Upgrade Notes |
|---|---|
buttonIcons repurposed! | Repurposed to affect button icons when themeing is off. Use themeButtonIcons for when themeing is on. |
buttonText | Text is now escaped. HTML injection won't work. |
viewDisplay callback | Previously deprecated and now removed |
disableDragging | |
disableResizing |
nextDayThreshold as been added to
prevent events which span past midnight from appearing as if they are multi-day.
The HTML markup for buttons in the header has changed slightly, as well as the CSS method used to inject icon characters into those buttons.
Timed events (events that are not all-day) can no longer be resized via the mouse in month and the basic views.
AMD Module
FullCalendar now registers itself as an AMD module for use with loaders like RequireJS.
When loaded in this manner, it attaches itself to the jquery the AMD system provides.
No More IE7 Support
Official support for IE7 has been dropped but support for IE8 and above remains.