Easy Date Handling in JavaScript with apex.date

Working with dates and times in pure JavaScript is painful, to say the least. In Oracle APEX 21.2, the APEX team introduced the apex.date JavaScript API. The apex.date API provides several easy-to-use utility functions that make formatting, parsing, comparing, and performing calculations on dates in JavaScript a breeze. What I like about these functions is that many mirror SQL and PL/SQL functions and operators we know and love. In this APEX 🩳, I will demonstrate three examples.

Example 1 - Date Calculations

The first example demonstrates a typical scenario where users must enter a start and end date. Whenever the user changes the start date, we want to default the end date to the start date plus seven days. In this scenario, P70_START_DATE is the 'Start Date', and P70_END_DATE is the 'End Date'. We have an 'Execute JavaScript Code' Dynamic Action on P70_START_DATE that triggers whenever the value changes and sets the appropriate value in P70_END_DATE.

Here is the complete code for the Dynamic Action:

/* Set dateFormat with the Date Format String for the APEX Session.
   Note: apex.date does not support all Oracle Format Strings 
     (see the documentation for details)
*/
const dateFormat   = apex.locale.getDateFormat();
// Set the number of days to add to the start date.
const addDays      = 7;
// Get the string value of the start date APEX Item.
var   startDateStr = apex.item("P70_START_DATE").getValue();
// Use apex.date.parse to convert the string date value to 
// a date value understood by apex.date
var   startDate    = apex.date.parse(startDateStr, dateFormat);
var   endDateStr   = "";
// Add 7 days to the startDate.
apex.date.add(startDate, addDays, apex.date.UNIT.DAY);
// Convert date back to a String using the date format of the session.
endDateStr = apex.date.format( startDate, dateFormat);
// Set the End Date value in the APEX Item.
apex.item( "P70_END_DATE" ).setValue(endDateStr);

The final parameter of apex.date.add identifies the unit (DAY,HOUR,YEAR, etc.). I am adding days in my example, so the unit is DAY. See the documentation for a complete list. We can also use apex.date.subtract to subtract date/time values.

By changing the type of Dynamic Action from 'Execute JavaScript Code' to 'Execute Server-side Code', we could have used PL/SQL to achieve the same thing.

The benefit of the JavaScript approach is that we avoid a round trip to the database in order to do this simple calculation.

Example 2 - Date Comparisons

In this example, we are checking to make sure the end date is greater than the start date. The javascript below uses apex.date.isAfter to achieve this.

const dateFormat   = apex.locale.getDateFormat();
var   startDateStr = apex.item("P70_START_DATE").getValue();
var   endDateStr   = apex.item("P70_END_DATE").getValue();
var   startDate    = apex.date.parse(startDateStr, dateFormat);
var   endDate      = apex.date.parse(endDateStr, dateFormat);
// Clear any existing errors on the page
apex.message.clearErrors();
// apex.date.isAfter compares the two dates down to the second.
if (apex.date.isAfter( startDate, endDate, apex.date.UNIT.SECOND))
{

  apex.message.showErrors([
      {
          type:       "error",
          location:   ["inline" ],
          pageItem:   "P70_END_DATE",
          message:    "End Date must be after Start Date"
      }
  ]);
}

There are other comparison functions available in apex.date, including isBefore, isBetween, isSame, isSameOrAfter, etc.

Example 3 - Since

You may have encountered the APEX PL/SQL function APEX_UTIL.GET_SINCE. It returns a string describing the elapsed time between a date and time variable and the current date and time. In this example, we use apex.date.since to achieve the same thing as APEX_UTIL.GET_SINCE.

const dateFormat   = 'MM/DD/YYYY HH:MIpm'
var   startDateStr = '07/04/2022 5:00pm';
var   startDate    = apex.date.parse(startDateStr, dateFormat);
var   sinceString = apex.date.since( startDate );
console.log('Since String: ' + sinceString);

Output from the above snippet: Since String: 13 minutes ago

Conclusion

This blog post was just a taste of the utilities available in apex.date. I encourage you to explore the documentation to find out more.

🔗 Read More

• 🩳 APEX Shorts
• #️⃣ APEX Posts