Lately I’ve been thinking a lot about data portability in terms of API’s, microformats and standards like SIOC, FOAF, OWL and APML. What fascinates me is that data portability enables people to share and move their data around the web seamlessly. I wrote about some microformats and standards for the semantic web a few days ago, but what about the API’s?

Nowadays, an API most often comes in the form of a REST service that returns JSON or XML, so that both JavaScript and server-side technologies can use them. It makes sense and it promote data portability. Then think about a website. Some parts of it are tagged up with various microformats like XFN, hCard and hCalendar, but what about the rest of the content?

My idea is to render any webpage in either XML or JSON if a certain parameter is added to the URL. It could look like this:

www.example.com/about.aspx?format=xml

Then the about.aspx page would render the output as XML for machines to read and thereby have some sort of read-only API. The standard could be RSS or ATOM or both. Now any machine can read the content of your website easily. Think about how easy it must be for search engines to index an RSS representation of a webpage instead of going through all the excess mark-up and style information.

If any webpage could be served as RSS, ATOM and JSON then the content of that page could be consumed in a multitude of ways. The best thing is that it is relatively easy to implement. Because it is so easy I can’t stop wondering if there is a reason no one has done it before.

The question is who would use this and does it make any sense to begin with?

Warning: The following post has the same effect as 19 cups of coffee before bedtime. If you are in doubt you will be able to handle it, I suggest you don’t read any further.

Every once in a while, you are presented with a product or a design or even an idea that you immediately think is da bomb even though you can’t really explain why. It may not be all that brilliant, but there is something lovable about it you can’t ignore or easily forget. It stays with you in your dreams until you go purchase the product or implement in your own. It’s what showbiz calls the x-factor.

What I have for you today, dear reader is nothing less than that. A method you need for all your projects, but have never realized it before. Trust me when I say that you might as well implement it everywhere right now or you are going to lose a lot of sleep until you do. Hold on to your seat and get ready to be amazed.

Let’s start by seeing what it is you do wrong today when you code your software and then see how to make it much better with a little brilliance.

The problem

When writing an application for either web or desktop, we often display dates and time to the visitor or user. It could be the date and time of an invoice or the time of arrival somewhere. What we have done in the past is simply writing out the time in a pretty boring way like so:

11:48:09 PM
or
23:48:09

You might be wondering what is wrong with the given examples and I understand that, because that is the way time has always been formatted in most parts of the world. In other parts the delimiter might be a dot or comma, but otherwise pretty much the same.

Now ask yourself if it is important for your users to know the precise time down to the minute and do they care about the seconds? The answer in most cases is a laud and clear NO. Nobody cares. We’ll ignore the cases where users do care because that would give us a laud and clear NO in 100% of the cases.

The solution

We just established that 100% of your users do not care about precise stated time. Instead let’s give them something that makes sense. Enter the brilliant method you didn’t know you needed.

The method is called ConvertToRelativeTime and it takes a DateTime as parameter and returns a string. If we stick to the above examples of the time 11:48:09 PM and feed it as a parameter to the brilliant method, then we get this output:

A quarter to midnight

Other outputs could be:

Half past eleven pm
About three am
A quarter past eight am 

I’ll give you a few seconds to wipe off the hot coffee you just spilled in your lap…

In a busy world where time is everything and money is made by the second, we need to relax when we can. This is one such way. A sort of an anti-stress approach to time display.

The idea about relative time is not mine. I got it from 37signals who got it from someone else. I fell in love with it the moment I saw it, and for the past week I’ve been dreaming and losing sleep because of it – just like you will. You don’t need to worry though, because I have written the code for you to grab and implement.

The code

Ok, it's actually two methods - a public and a private helper to the public. 

public static string ConvertToRelativeTime(DateTime date)

{

  string relative = string.Empty;

  int hour = date.Hour;

  string meridian = date.Hour > 12 ? "pm" : "am";

 

  if (date.Minute < 8)

  {

    relative = "about";

  }

  else if (date.Minute > 52)

  {

    relative = "about";

    hour++;

  }

  else if (date.Minute < 22)

  {

    relative = "a quarter past";

  }

  else if (date.Minute < 38)

  {

    relative = "half past";

  }

  else if (date.Minute <= 52)

  {

    relative = "a quarter to";

    if (hour == 23)

    {

      hour = 0;

      meridian = string.Empty;

    }

    else

    {

      hour++;

    }

  }

 

  if (hour == 0)

  {

    meridian = string.Empty;

  }

 

  string name = GetHourText(hour);

  return relative + " " + name + " " +  meridian;

}

 

private static string GetHourText(int hour)

{

  if (hour > 12)

    hour = hour - 12;

 

  switch (hour)

  {

    case 1: return "one";

    case 2: return "two";

    case 3: return "three";

    case 4: return "four";

    case 5: return "five";

    case 6: return "six";

    case 7: return "seven";

    case 8: return "eight";

    case 9: return "nine";

    case 10: return "ten";

    case 11: return "eleven";

 

    default:

      if (hour == 0)

        return "midnight";

      else

        return "twelve";

  }

}

If you tweak it a bit you can display time in even more relative terms. What about these examples:

Two and a half hour to lunch
About an hour past bedtime
Work day ends in about 3 hours