As John already teased in his blog post about the JavaScript API changes in APEX 21.2, there is a new apex.date namespace coming.
Main purpose of it is to have an out-of-the-box replacement for Moment.js which is part of APEX since we introduced our Calendar region with FullCalendar version 3. In APEX 21.1 this region was updated to use the newer version 5 of the underlying FullCalendar library, and this particular version doesn't come with Moment.js anymore and changed many other things, especially from an API point of view. If you're interested in these changes in more detail, we created a blog posting back when 21.1 was released to help developers to get started with this new version.
Additionally even Moment.js itself states, that you shouldn't use this library anymore:
So we thought it would be really helpful for all APEX developers to have an integrated API which can do most of the things Moment.js did + things that make sense in an APEX or database environment.
There are 4 main categories in which you will find functions to use in apex.date:
Before starting with the description of the actual categories and showing some code examples, it is worth to mention that apex.date operates with native JavaScript date objects and doesn't introduce new custom objects like Moment.js did.
var date = new Date();
Date Manipulation
This category contains functions to manipulate JavaScript date objects, like adding or subtracting given amounts to or from a date.
So lets add something to a given date:
var date = new Date();
apex.date.add( date, 2, apex.date.UNIT.YEAR );
apex.date.add( date, 5, apex.date.UNIT.DAY );
apex.date.add( date, 45, apex.date.UNIT.MINUTE );
console.log( date );
And now lets subtract something from a date:
var date = new Date();
apex.date.subtract( date, 2, apex.date.UNIT.MONTH );
apex.date.subtract( date, 30, apex.date.UNIT.SECOND );
apex.date.subtract( date, 4, apex.date.UNIT.WEEK );
console.log( date );
As you can see, we used the apex.date.UNIT object in both examples, this has constants for all units used by apex.date
In this category there's everything related to date formatting & parsing. The most important part to mention is that apex.date handles it formatting & parsing logic using Oracle Database compatible format masks, which makes it easy for APEX developers to re-use their DB logic also on the client, without investigating too much brain power in thinking in 2 separate format mask flavors.
Date formatting:
var date = new Date(),
dateString = "";
dateString = apex.date.format( date, "YYYY-MM-DD HH24:MI:SS" );
dateString = apex.date.format( date, "YYYY/MM/DD" );
dateString = apex.date.format( date, "YYYY, IW" );
dateString = apex.date.format( date, "Day, DD Month YYYY" );
dateString = apex.date.format( date, "DL" );
dateString = apex.date.format( date, "DL", "de" );
dateString = apex.date.format( date, "DL", "es" );
dateString = apex.date.since( date );
dateString = apex.date.since( date, true );
Date parsing:
var date;
date = apex.date.parse( "2021-10-11 22:15", "YYYY-MM-DD HH24:MI");
date = apex.date.parse( "2021/10/11", "YYYY/MM/DD");
date = apex.date.parse( "2021-OCT-11 22:15:45", "YYYY-MON-DD HH24:MI:SS");
If no format or language is specified, apex.date automatically uses the format and language defined in your application. You can also get this information using:
apex.locale.getDateFormat();
apex.locale.getLanguage();
Date Comparison
This category contains functions useful to compare 2 or more JavaScript date objects with each other.
var date1 = apex.date.parse( "2021/10/01", "YYYY/MM/DD"),
date2 = apex.date.parse( "2021/10/15", "YYYY/MM/DD"),
date3 = apex.date.parse( "2021/10/31", "YYYY/MM/DD");
apex.date.isBefore( date1, date2, apex.date.UNIT.DAY );
apex.date.isAfter( date1, date2, apex.date.UNIT.DAY );
apex.date.isSame( date1, date2, apex.date.UNIT.DAY );
apex.date.isSameOrBefore( date1, date2, apex.date.UNIT.DAY );
apex.date.isSameOrAfter( date1, date2, apex.date.UNIT.DAY );
apex.date.isBetween( date1, date2, date3, apex.date.UNIT.DAY );
var minDate = apex.date.min( date1, date2, date3 );
var maxDate = apex.date.max( date1, date2, date3 );
Most compare functions are also utilizing apex.date.UNIT constants. This enables developers to precisely compare dates from milliseconds up to years.
Miscellaneous
Beside the other categorized functionality, apex.date also has more generic functions or useful helper functions on board, which I won't describe here in full length, but to just get an idea, here are a few of them:
var date = new Date();
var week = apex.date.ISOWeek( date );
var days = apex.date.daysInMonth( date );
var first = apex.date.firstOfMonth( date );
var last = apex.date.lastOfMonth( date );
var months = apex.date.monthsBetween( now, date );
var isLeapYear = apex.date.isLeapYear( date );
The whole apex.date API documentation is part of our official JavaScript API documentation, which when APEX 21.2 is ready will be available here. I also plan to publish a demo app show casing everything in this post live in an APEX app. This app will be released as soon as 21.2 is available on apex.oracle.com.
Edit 18/11/2021: As promised, and now that APEX 21.2 pre-production release is available at apex.oracle.com, you can find the demo app here.
Happy APEXing! 🚀