With the release of APEX 21.1, and beside other larger new features, also the Calendar Region got some attention and was updated. The main new features or changes are
Faceted Search integration
Declarative lazy loading option
Removed client side Google Calendar integration
Removed client side REST Webservice (JSON) integration
FullCalendar library updated to version 5 (5.5.1)
Thus these changes also have an impact on custom code developers might have written around the standard Calendar Region this posting should help to make things clearer and assist you with upgrading current calendars to the new version.
1. The end users experience!
At runtime the new version 5 calendar behaves and pretty much looks like the existing calendar (which used FullCalendar version 3). So things like drag & drop, keyboard navigation, different calendar views (like month, week, day or list) are still working as expected.
2. Existing calendars
If an environment was upgraded to APEX 21.1 or an existing older app was imported into an APEX 21.1 workspace, existing calendars won't be updated automatically and still use the older FullCalendar version 3 implementation. We decided to do that to not brake any existing apps or pages.
There are 2 options to really upgrade the calendar to the new version and also use new functionality like Faceted Search integration or lazy loading capabilities:
Using the Application Upgrade wizard (under App > Utilities > Upgrade Application) to automatically upgrade existing Calendar Regions
Manually upgrade a Calendar Region
Then the upgrade process itself is pretty simple. There's a new "Version" attribute on region level and by setting this to "FullCalendar 5" is enough to make use of the new functionality.
If the old calendar used one of the removed features, such as client side Google Calendar or REST Webservice (JSON) integration, then this has to be resolved before updating the calendar to the new version, otherwise this page will not work properly anymore.
Luckily both features can easily be transformed to make use of APEX REST Data Sources instead of doing an HTTP request on the client browser.
The provided REST Data Sources can then be used as a Region Source instead of a SQL statement.
The deprecated REST Webservice (JSON) functionality should be straight forward, the Google Calendar API on the other hand needs additional information, such as an API Key and the calendar ID of a publicly shared calendar. The documentation could be found here.
The REST endpoint URL to include a public Google Calendar looks like this:
A second way - without using declarative REST Data Sources - is using the APEX_DATA_PARSER API. A pretty unknown feature of it:
It also can parse calendar ICS files pretty well, so this would enable us to directly use the public iCal address of an Google calendar or any other calendar. A query to parse and get calendar's data could look like this:
Such a query can then be provided as the region source of a Calendar Region.
For further information about all options and possibilities, have a look at the official FullCalendar documentation. If someone is interested in what exactly has changed between version 3 and the current version 5, there are upgrade guides available as well:
These are 2 examples to compare the same functionality between the old version 3 and version 5:
Even though both code snippets would result in the same output, there are quite some differences between the versions:
Let's compare some commonly used API calls between the 2 versions:
For those of you, which heavily used moment.js for date manipulation: We're planning to create our own date utility API in a future APEX release, which when ready, will support most of moment.js functionality, to make date operations & manipulations much easier to use.
We hope this post helps you to get your hands on the updated calendar component and make the upgrade experience much more straight forward, even when you used advanced features & customizations.
As a side note: We are also planning to remove the FullCalendar version 3 implementation completely in a future APEX release, so now would be the perfect time to upgrade your existing calendars! :)