Sensible DateTime | jQuery Plugin

Introduction

There are a handful of Javascript libraries that convert date on your page to relative time or format them. However, they are usually set in their predefined way.

Sensible DateTime provides more flexibility that helps display date and time on the website according to your specific needs and context.

Example

Markup

<p>You opened this page <abbr class="datetime opened">opened time</abbr>.<!-- dynamically generated --></p>
<p>Someone posted something <time class="datetime" datetime="2011-09-27T15:40:00">2011, Sep 27th</time></p>
<p>John shared his photo <time class="datetime" datetime="2011-09-26T11:42:11">9-26-2011</time></p>
<p>Jane closed issue 12 <time class="datetime" datetime="2011-09-21T02:27:42">2011, September 21</time></p>
<p>Harry started using jQuery <abbr class="datetime" title="2011-08-12T14:51:03">Aug 12</abbr></p>
<p>Sent an email <time class="datetime" datetime="2001-12-25T11:21:53">2011 12/25</time></p>
<p>I was born <abbr class="datetime" title="1984-05-15T00:00:00">May 15th, 1984</abbr></p>

Turns into this by default

You opened this page opened time.

Someone posted something 2011, Sep 27th

John shared his photo 9-26-2011

Jane closed issue 12 2011, September 21

Harry started using jQuery Aug 12

Sent an email 2011 12/25

I was born May 15th, 1984

However, you can change how they are displayed with different options.

Option 1 (Relativity rules) | Option 2 (Minimalist)

How to use

Download latest version here (last updated 2011, Sep 27th)

If you use tags other than time to markup the datetime. The tag should have ISO8601 datetime string as the value of title attribute.

HTML5 introduced a new tag called time that has datetime attribute. You can use the new time tag with ISO8601 datetime string as the value of datetime attribute.

Once you are ready, call the plugin like this

$(function() {
  $('.datetime').sensible();
});

Optionally, you can pass an object to override the default setting.

shortDayNames: array of short names for days
longDayNames: array of long names for days
shortMonthNames: array of short names for months
longMonthNames: array of long names for months
refreshRate: how often do auto-update in milliseconds
pastMask: used for any datetime that is more past than a year (by default) or what you specified
futureMask: used for any datetime that is in the future
masks: an array of objects that specify a distance (distance of seconds from the current time) and a mask (how to display datetime within that distance)

When your define your masks, you can use any combination of flags from the list below to specify which information you want to show. Or none, if you don't want to :(

%d - the day of the month (1-31)
%dd - the day of the month (00-31)
%ddd - the short name of the day (Mon - Sun)
%dddd - the long name of the day (Monday - Sunday)
%m - the month (1 - 12)
%mm - the month (01 - 12)
%mmm - the short name of the month (Jan - Dec)
%mmmm - the long name of the month (January - December)
%yy - the year (00 - 99)
%yyyy - the year (0000 - 9999)
%h - the hour (0 - 12)
%hh - the hour (00 - 12)
%H - the hour (0 - 24)
%HH - the hour (00 - 12)
%M - the minutes (0 - 59)
%MM - the minutes (00 - 59)
%s - the seconds (0 - 59)
%ss - the seconds (00 - 59)
%t - a or p
%tt - am or pm
%T - A or P
%TT - AM or PM
%S - Ordinal of the day (st, nd, rd, th)
%xs - distance from now in seconds
%xm - distance from now in minutes
%xh - distance from now in hours
%xd - distance from now in days
%xy - distance from now in years

Reference

Here are the default setting values

var settings = {
  shortDayNames: [
    'Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'
  ],
  longDayNames: [
    'Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday',
    'Friday', 'Saturday'
  ],
  shortMonthNames: [
    'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
    'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
  ],
  longMonthNames: [
    'January', 'February', 'March', 'April', 'May', 'June',
    'July', 'August', 'September', 'October', 'November', 'December'
  ],
  refreshRate: 60000,
  pastMask: '%mmmm %d, %yyyy at %h:%MM%tt',
  futureMask: '%mmmm %d, %yyyy at %h:%MM%tt',
  masks: [
    {
      // within a minute
      distance: 60,
      mask: 'just now'
    },
    {
      // within 2 minutes
      distance: 120,
      mask: 'about a minute ago'
    },
    {
      // within 1 hour
      distance: 3600,
      mask: '%xm minutes ago'
    },
    {
      // within 2 hours
      distance: 7200,
      mask: 'about an hour ago'
    },
    {
      // within 24 hours
      distance: 86400,
      mask: '%xh hours ago'
    },
    {
      // within 48 hours
      distance: 172800,
      mask: 'Yesterday at %h:%MM%tt'
    },
    {
      // within this year
      distance: 31556926,
      mask: '%mmmm %d at %h:%MM%tt'
    }
  ]
};

Got something?

If you have any question or feedback, drop me an email at jwoongkim@gmail.com.

If there is a bug or problem, create a issue at GitHub or fork it and send a pull request.

License

MIT License