New apex.date JS API in APEX 21.2
5 min read
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:
Date Formatting & Parsing
var date = new Date();
So lets add something to a given date:
var date = new Date(); // add 2 years apex.date.add( date, 2, apex.date.UNIT.YEAR ); // add 5 days apex.date.add( date, 5, apex.date.UNIT.DAY ); // add 45 minutes apex.date.add( date, 45, apex.date.UNIT.MINUTE ); console.log( date );
And now lets subtract something from a date:
var date = new Date(); // subtract 2 months apex.date.subtract( date, 2, apex.date.UNIT.MONTH ); // subtract 30 seconds apex.date.subtract( date, 30, apex.date.UNIT.SECOND ); // subtract 4 weeks 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
Date Formatting & Parsing
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.
var date = new Date(), dateString = ""; dateString = apex.date.format( date, "YYYY-MM-DD HH24:MI:SS" ); // output: 2021-10-11 22:15:45 dateString = apex.date.format( date, "YYYY/MM/DD" ); // output: 2021/10/11 dateString = apex.date.format( date, "YYYY, IW" ); // output: 2021, 41 dateString = apex.date.format( date, "Day, DD Month YYYY" ); // output: Monday, 11 October 2021 dateString = apex.date.format( date, "DL" ); // output: Monday, October 11, 2021 dateString = apex.date.format( date, "DL", "de" ); // output: Montag, 11. Oktober 2021 dateString = apex.date.format( date, "DL", "es" ); // output: lunes, 11 de octubre de 2021 // relative date / time as words dateString = apex.date.since( date ); // output: "10 months from now" or "2 months ago" dateString = apex.date.since( date, true ); // output: "in 10mo" or "2mo"
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:
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"); // is date 1 < date 2 apex.date.isBefore( date1, date2, apex.date.UNIT.DAY ); // output: true // is date 1 > date 2 apex.date.isAfter( date1, date2, apex.date.UNIT.DAY ); // output: false // is date 1 = date 2 apex.date.isSame( date1, date2, apex.date.UNIT.DAY ); // output: false // is date 1 <= date 2 apex.date.isSameOrBefore( date1, date2, apex.date.UNIT.DAY ); // output: true // is date 1 >= date 2 apex.date.isSameOrAfter( date1, date2, apex.date.UNIT.DAY ); // output: false // is date 1 between date 2 and date 3 apex.date.isBetween( date1, date2, date3, apex.date.UNIT.DAY ); // output: false // get the minimum date of given date arguments var minDate = apex.date.min( date1, date2, date3 ); // output: date1 as date object // get the maximum date of given date arguments var maxDate = apex.date.max( date1, date2, date3 ); // output: date3 as date object
Most compare functions are also utilizing apex.date.UNIT constants. This enables developers to precisely compare dates from milliseconds up to years.
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(); // get ISO week number var week = apex.date.ISOWeek( date ); // get total days of month var days = apex.date.daysInMonth( date ); // get first of month as date object var first = apex.date.firstOfMonth( date ); // get last of month as date object var last = apex.date.lastOfMonth( date ); // get months between 2 dates var months = apex.date.monthsBetween( now, date ); // check if it's a leap year var isLeapYear = apex.date.isLeapYear( date );
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! 🚀