Your Development & Design Resource
Using SimpleDateFormat for Date and Time formatting in IBM Domino XPages
05/21/2018 by Chris Toohey
We're going to use the java.text.SimpleDateFormat Class in Java to create some global format variables for use throughout our application. For demo purposes, let's say you want three specific syntaxes for your dates/times:
- A simple date format ("05/21/2018").
- A simple time format ("12:45 PM").
- A simple date+time format ("05/21/2018 12:45 PM")
Before we get started, let's take a look at the "java.text.SimpleDateFormat" Java Class.
You'll see that we can easily establish a date and time pattern using a combination of "pattern letters" which themselves represent specific values of the date/time we're looking to present. If we use the pattern letters key on the Class documentation, our three syntaxes from above can be expressed like this:
|"05/21/2018 12:45 PM"||
Now that you have your global variables in your SSJS library, let's see how we use them in our SSJS and XPages.
The "java.text.SimpleDateFormat" Java Class has a "format" Method. This method allows you to pass a Date ("java.util.Date" Java Class), as well as a StringBuffer and FieldPosition arguments (but we're not going to be using those for this example).
Let's say we want a function that returns a String representation of the first day of this year. In other words, we're looking for "01/01/2018" to be returned when you run the function on any date in 2018. Weird example, I know, but I'm purposefully keeping this simple...
The results of the
getFirstOfYear() function will - today and for the rest of 2018 - be the String "01/01/2018".
-- and you might be asking me why we jumped through all of those hoops when we could have just done something like this:
-- or this combo of
-- and I'd let you know that (aside from being terribly steeped in the old-timey ways of Notes @Formula String manipulation) both of these approaches break our desired pattern of "MM/dd/yyyy".
Both of the hack functions above will return the two-digit year "18" giving you "01/01/18" vs. our desired four-digit year "2018" and "01/01/18". In fact,
@Now() itself when printed or otherwise converted to a String will give you an abbreviated value. For example, if I were to do a
print(@Left(@Now(), " ")); in SSJS today only "5/18/2018" would print to the console.
And perhaps you want to change the display of your dates from a "MM/dd/yyyy" to a "yyyy/MM/dd" format. We could easily change the
dateFormat global variable above to use the new pattern and udpate every single instance of our dates - not as they're stored in the system, but rather in how they're displayed in the application.
Let's take a look at how our complete SSJS library looks along with a more "complex" use case:
At the beginning we define our global java.text.SimpleDateFormat varables for "date", "time", and "datetime" patterns. Next, we have our "first of the current year" function, followed by an "last day in the month" function.
You should now be able to read this function (even though I slipped in the "java.util.Calendar" Class). We're simply using
@Now() to get a handle of which month we're in, and then returning a String representing the end of the current month using the same pattern all of our other dates using the "date" pattern SimpleDateFormat.
There are countless use cases for this method including (but certainly not limited to) the display of dates or times in View columns, xp:text controls without the need for a converter, and String building functions where a simple
_thisString += dateFormat.format(_someDateValue); will quickly and consistently allow you to handle Dates and Times for your XPages applications.
It's my favorite type of method: it allows me to easily maintain a consistent component that may be used hundreds of times in one of my applications... and if we're ever bought out by a European company I can change a single line of code to make sure our Performance Management Goals are due on February 1st vs. January 2nd!