Human Readable Dates -- LotusScript Version of Ruby's Time_Ago_In_Words

One of the things I've always wanted to reproduce in Notes is Ruby's time_ago_in_words function. You've probably seen it in use, even if you didn't realise. Ever seen a website where the creation date of entries on it are shown not as a date but as a description of how long ago it was in words. Example include:

  • This was posted less than a minute ago.
  • This entry was created about 2 hours ago.

There are more examples if you follow the link I posted above. You get the idea though, right?

What I love about it is the way (as a user) you get an instant idea of when it happened. It seems a much better way for the human mind to get an idea of the timescales involved. While displaying a normal date works it just isn't as easy for the user to digest.

You can see an example of the principle in use on Digg.com. See this search for page. Notice each result has the time is was "made popular" next to it in (red) human-readable text.

Not wanting to procrastinate any longer I finally got round to porting the code to LotusScript. You can see the original Ruby code/logic in the link above if you click "show source".

Here's the LotusScript class I created. To use in LotusScript, you just do this:

Dim d As New DateHelper 
Print DEXT.Document.Since(0) + " is "
        + d.TimeSince(DEXT.Document.Since(0), True)

In this case the code is from a WQS agent of a Form which has a DateTime field on it called "Since". You can see an example of it in use here.

Do us a favour and test the logic out would you? I know it doesn't handle future dates yet but how well do you think it handles past dates?

Putting It To Use

How useful is this function to us Notes developers? We're used to using Views to show documents. This method can't be used in Views though as they wouldn't be able to index. It's only really useful if you're using a WQO Agent to display a set of documents.

As an example, take the calendar view in the DEXT demo. This whole "view" is generated on the fly by a LotusScript WQO agent. Notice now that the time the entry was added is show below the title in "words".

So, what do you think?


    • avatar
    • Niel R
    • Tue 9 Sep 2008 08:22 AM

    Very cool, of course I had to see what happened with a future date (I know it's not intended for that).

    • avatar
    • Jake Howlett
    • Tue 9 Sep 2008 08:32 AM

    It's not that it's not intended for it Niel. Just that I am too lazy to add it in. I'll do it now.

    It's just as applicable to future dates as past. Imagine an application where you had a list of events coming up and wanted them listed as "X is 2 days away, Y is 3 months away" etc.

    Off to add future date handling...

    • avatar
    • Jake Howlett
    • Tue 9 Sep 2008 08:48 AM

    Code updated to handle future dates. Logic is the same, but the word "ago" or "away" is appended, depending on whether the sign of the TimeDifference() result is positive or negative, respectively.

  1. When I entered "02/16/2000 10:07:20 AM", got back that "over 9 years ago". Looks like a calculation error somewhere.

  2. Nice!

    • avatar
    • Jake Howlett
    • Tue 9 Sep 2008 10:25 AM

    You're right Granvel. That does seem odd. The code was rounding the number of years and then saying "over". So if it was 8.8 years ago it would say "over 9", which is quite obviously wrong. I've changed the word over to say "about" now ;o)

    Thanks Jon!


  3. Enter this date (or any before it.. I originally tried 1900) in the example:

    09/09/1939 06:04:49 PM

    and the result becomes incorrect:

    That time is about 67 years away

    A 1900 date returns that it is about 28 years away.

    • avatar
    • Jake Howlett
    • Wed 10 Sep 2008 03:36 AM

    This looks like a limitation of the TimeDifference() method Joel.

    It returns a Long data type, for which the limit is 2,147,483,647. This takes us back from now until about 1940.

    Seems reasonable to expect only dates within the given limits though.


  4. I very much like this. I have been using FuzzyClock {Link} on my Mac which essentially replaces the clock with fuzzy time. After all, I don't really need to know that it is 2:58; "nearly three" is good enough. Anyway, I really find this an interesting idea.

  5. I like it and have bookmarked it for future use. Thanks Jake!

  6. How about "two weeks from today"?

  7. Nice tip Jake...I've added a formula version of this to a brand new Helpdesk app I've just deployed. The users love it when it says "...to go" but not when it says "...late" :)

    Thanks for inspiring!

  8. The formula version I came up with. Please let me know if you see anything wrong or have any ideas to improve on it:

    diff_in_seconds:=@Now - datYourFieldName;


    @If(future;whichWay:= " away";whichWay:= " ago");



    diff_in_minutes >= 0 & diff_in_minutes <= 1; since:="about a minute";

    diff_in_minutes >= 2 & diff_in_minutes <= 44;since:=@Text(diff_in_minutes) & " minutes";

    diff_in_minutes >= 45 & diff_in_minutes <= 89;since:= "about 1 hour";

    diff_in_minutes >= 90 & diff_in_minutes <= 1439;since:= "about " + @Text(@Round(@Abs(diff_in_minutes)/60)) + " hours";

    diff_in_minutes >= 1440 & diff_in_minutes <= 2879;since:= "1 day";

    diff_in_minutes >= 2880 & diff_in_minutes <= 43199;since:= "about " + @Text(@Round(@Abs(diff_in_minutes)/1440)) + " days";

    diff_in_minutes >= 43200 & diff_in_minutes <= 86399;since:= "about 1 month";

    diff_in_minutes >= 86400 & diff_in_minutes <= 525599;since:= "about " + @Text(@Round(@Abs(diff_in_minutes)/43200)) + " months";

    diff_in_minutes >= 525600& diff_in_minutes <= 1051199;since:= "about 1 year";

    since:="over " + @Text(@Round(@Abs(diff_in_minutes)/525600)) + " years" );

    since + whichWay

  9. I've ported this code across to Server Side Javascript to use in an XPages app, thanks Jake... http://mattwhite.me/blog/2009/6/28/human-readable-dates-in-xpages.html

Your Comments


About This Page

Written by Jake Howlett on Tue 9 Sep 2008

Share This Page

# ( ) '


The most recent comments added:

Skip to the comments or add your own.

You can subscribe to an individual RSS feed of comments on this entry.

Let's Get Social

About This Website

CodeStore is all about web development. Concentrating on Lotus Domino, ASP.NET, Flex, SharePoint and all things internet.

Your host is Jake Howlett who runs his own web development company called Rockall Design and is always on the lookout for new and interesting work to do.

You can find me on Twitter and on Linked In.

Read more about this site »

More Content