I've been working on a simple project for handling date and time ranges in JS. I have a long ways to go, but I have the first part working well: formatting date ranges. And that makes for a good introduction to the topic as a whole, so I figured I'd blog about it.

Displaying time ranges

See, formatting date ranges so they can be read naturally isn't very easy. The general format on the web is something like:

Jan 26, 7:00 PM - Jan 26, 9:00 PM

Which isn't something you'd ever say, but it's what happens when you treat a date range as nothing more than two dates, call toString() on each one, and then join them with a dash. It's easy, so everyone does it.

But what I want to say is:

Jan 26, 7 - 9 PM

You might disagree. Maybe you live in France or something, and you want to say:

Jan 26, 19:00 - 21:00

Or maybe you're just the verbose type and want:

Thursday January 26th, 7pm - 9pm

Twix

In any case, I have a JS library that can handle that. It's called Twix.js, and it's pretty cool. Here are those three examples:

//takes dates or parses them
var twix = new Twix("1/26/2012 7:00 PM", "1/26/2012 9:00 PM");

twix.format()                           //=> Jan 26, 7 - 9 PM
twix.format({twentyFourHour: true})     //=> Jan 26, 19:00 - 21:00

//so I admit, this one is complicated
twix.format({
  showDayOfWeek: true,
  weekdayFormat: "dddd",
  monthFormat: "MMMM",
  dayFormat: "Do",
  groupMeridiems: false,
  spaceBeforeMeridiem: false,
  meridiemFormat: "a",
})                                     //=> January 26th, 7pm - 9pm

It can also handle all sorts of different range sizes as well as all-day events.

Get it

I have a lot left to do, but the formatting stuff seems usable. Comprehensive docs, downloads, and finger paintings live on Github.