Your Development & Design Resource

Using SimpleDateFormat for Date and Time formatting in IBM Domino XPages

Using SimpleDateFormat for Date and Time formatting in IBM Domino XPages

How many times have you wrestled with Date or Time formatting in LotusScript, @Formula, and now Server Side JavaScript? Sure, you have your preferred go-to method for returning "12:45 PM" or "Monday" for a given time/date... but here's one that you can use in Server Side JavaScript with an eye to your evolution as a Java-literate developer.

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:

  1. A simple date format ("05/21/2018").
  2. A simple time format ("12:45 PM").
  3. 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:

Example Pattern Letters
"05/12/2018" "MM/dd/yyyy"
"12:45 PM" "hh:mm aa"
"05/21/2018 12:45 PM" "MM/dd/yyyy hh:mm aa"

We have our pattern letters, so let's put them to use. To start, let's edit the Server Side JavaScript library that you're including in your XPage (or create a new one), and add the following SimpleDateFormat global variables:

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 @Left() and @RightBack()

-- 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!

About the author: Chris Toohey

Thought Leadership, Web & Mobile Application Development, Solutions Integration, Technical Writing & Mentoring

A published developer and webmaster of, Chris Toohey specializes in platform application development, solutions integration, and evangelism of platform capabilities and best practices.

More from is powered by IBM Notes Domino XPages & hosted by Prominic.NET

Contact Us

Use our Contact / Feedback form or one of these email addresses:

Creative Commons License

Except where otherwise noted, by Chris Toohey is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.