Human Readable Dates in XPages

If I display a date/time in a view I can enable the option “show ‘today’ if appropriate”. This will replace todays (or yesterdays) date with the text “Today” (or “Yesterday”). I wanted to have the same functionality in an Xpage-based application I’m creating, but couldn’t find the XPage equivalent.

After some searching on the web I found an article written by Matt White (Human Readable dates in XPages) in which he kind-of did the same: the SSJS library he created allows you to convert dates to a “time since” string (e.g. “2 hours ago”, “6 days ago”). Since what I wanted is also another way of displaying dates I decided to extend his class (and rename it while I’m at it). You’ll find the resulting class this (compressed) text file:

Usage instructions

Download the attachment and paste the code in an SSJS script library. Add the library as a resource to the Xpage(s) you’ll want to use the new date format on.

There are 2 ways to convert dates (example for a document with a “modifiedDate” date/time field)

1. use SSJS to compute and convert a value:

var myDateValue = document1.getItemValueDate("modifiedDate");

var d = new ReadableDate();


var d = new ReadableDate();

The first method will give you dates formatted like “Today 9:10”, “Yesterday 3:15”, “24 July 2:10”, the second will display the time since the specified date.

2. Bind a control to the date/time value/ field, set the display type to “String” and add a custom converter:

  • type= xp:customConverter
  • getAsObject: just enter “value” (javascript, without quotes)
  • getAsString: enter “ReadableDateConverter.getAsString()” (javascript, without quotes)

The ReadableDate class currently has 3 configuration options:

  • includeTime : will include the time when displaying a date.
  • includeSeconds : includes seconds when displaying the time.
  • includeYearIfCurrent : if true the year is always added, if false the year is only added if not the current year.

Since my app has a Dutch audience, I’ve added Dutch language strings to the class.

Beware of what getColumnValue is returning

When working with view columns that might contain multiple values, remember that the return value of the getColumnValue(“column”) method from the NotesXspViewEntry object is different depending on the number of values in the column of a specific view entry:

  • If the view entry contains a single value, a string is returned.
  • If the view entry contains multiple values, it returns a Vector.
If you always want to have a Vector as the return type, you’ll have to convert it:
var values = rowData.getColumnValue("MultiValueColumn");
if ( (typeof values).toLowerCase() == "string" ) {
 var vTmp = new java.util.Vector();
 values = vTmp;
Converting the return type is also a possible workaround when working with nested repeat controls: if you set the Iteration to yourRowData.getColumnValue(“MultiValueColumn”) the repeat control won’t work with rows containing a single value.