jQuery EasyDate

Introduction

EasyDate is a jQuery plugin to format dates into a human-readable form and continuously update them to stay accurate while the user remains on the page. The plugin will parse a RFC 1123 valid timestamp from a DOM element's title attribute or innerHTML property and format it into a human-readable form (e.g., "2 weeks ago").

EasyDate is currently undergoing initial releases and should not be considered stable for production use but is encouraged to be used for development. A stable release should be expected in the coming weeks. Please report any problems or feature requests via email.

Author:: Parsha Pourkhomami
Version:: 0.2.4 (Sun, 06 Dec 2009 18:12:00 -0800)
License:: MIT

Download

jQuery (1.3.2 or later required - compatible with 1.4.2)
EasyDate 0.2.4 minified (3.37KB)
EasyDate 0.2.4 (10.83KB)

Demo

Fri, 24 May 2013 07:31:50 -0700
Wed, 22 May 2013 22:01:50 -0700
Wed, 20 Mar 2013 04:01:50 -0700
more demos

Usage

HTML:


<abbr title="Fri, 24 May 2013 04:01:50 -0700" class="easydate"></abbr>
<abbr class="easydate">Fri, 24 May 2013 01:01:50 -0700</abbr>

JavaScript:


jQuery(function($) {
    $(".easydate").easydate([options]);
});

Note: the abbr element is not supported by IE6. Use a span or another element to support IE6.

Options

The easydate method takes one optional argument: an options object. The following properties can be defined. All properties are optional.

Property	Type	Description
`live`	Boolean	Determines if EasyDate should continuously keep dates updated. If set to false, dates will be static. Default: `true`
`set_title`	Boolean	Determines if EasyDate should set the title attribute of the DOM element to the original RFC 1123 timestamp if the title attribute is empty. Default: `true`
`format_future`	Boolean	Determines if EasyDate should format dates that are in the future. Default: `true`
`format_past`	Boolean	Determines if EasyDate should format dates that are in the past. Default: `true`
`units`	Array	This property is an array of unit objects. The array must be sorted in order of ascending unit limits. The unit object has the following properties: `name` The name of the unit - used in localization. `limit` The non-inclusive upper limit (in seconds) of this unit. For example, the limit of "second" is 60 as after 60 seconds the unit of time becomes "minute". If you wanted seconds to count all the way to 100, you would use a limit of 100. `in_seconds` (optional) The conversion of this unit to seconds. For example, there are 3600 seconds in an hour, so the `in_seconds` property of "hour" is 3600. Some units cannot be converted to seconds as they are "time concepts" as opposed to "time units" (e.g., "yesterday") and in these cases the `in_seconds` property can be omitted. When this property is omitted "ago" and "in" are not appended and preprended to the unit. `past_only` (optional) Flags the unit to be used only in past dates. For example, this is applicable to "yesterday". `future_only` (optional) Flags the unit to be used only in future dates. For example, this is applicable to "tomorrow". units: [ { name: "now", limit: 5 }, { name: "second", limit: 60, in_seconds: 1 }, { name: "minute", limit: 3600, in_seconds: 60 }, { name: "hour", limit: 86400, in_seconds: 3600 }, { name: "yesterday", limit: 172800, past_only: true }, { name: "tomorrow", limit: 172800, future_only: true }, { name: "day", limit: 604800, in_seconds: 86400 }, { name: "week", limit: 2629743, in_seconds: 604800 }, { name: "month", limit: 31556926, in_seconds: 2629743 }, { name: "year", limit: Infinity, in_seconds: 31556926 } ] `units: [ { name: "microfortnight", limit: 1209.6, in_seconds: 1.2096 }, { name: "millifortnight", limit: 1209600, in_seconds: 1209.6 }, { name: "fortnight", limit: Infinity, in_seconds: 1209600 } ]`
`uneasy_format`	Function	A function that is used to format the date if the date does not fall within any units' limits. For example, if the maximum unit is "hour" with a limit of 86400 seconds (one day), then this function will be used to format the date once it is more than one day in the future or past. The function is passed a date object as the only argument. `uneasy_format: function(date) { return date.toLocaleDateString(); }` `uneasy_format: function(date) { return date.getMonth() + "/" + date.getDay() + "/" + date.getFullYear(); }`
`locale`	Object	An object containing key/value pairs for all localization strings needed by EasyDate. In addition to "in" and "ago", all unit names (in both singular and plural forms) should be defined. Two special keys exist for string formatting (`future_format` and `past_format`). These strings determine how past and future dates are formatted. This is necessary because wether the localized "ago" and "in" come before or after the time unit is locale dependant. For example, in English "ago" comes after the time unit ("10 minutes ago") - whereas in Spanish it comes before ("hace 10 minutos"). `%s` is replaced with the localized "ago" or "in" and `%t` is replaced with the localized time unit. `$.easydate.locales.enUS = { "future_format": "%s %t", "past_format": "%t %s", "second": "second", "seconds": "seconds", "minute": "minute", "minutes": "minutes", "hour": "hour", "hours": "hours", "day": "day", "days": "days", "week": "week", "weeks": "weeks", "month": "month", "months": "months", "year": "year", "years": "years", "yesterday": "yesterday", "tomorrow": "tomorrow", "now": "just now", "ago": "ago", "in": "in" };` `locale: { "future_format": "%s %t", "past_format": "%s %t", "second": "segundo", "seconds": "segundos", "minute": "minuto", "minutes": "minutos", "hour": "hora", "hours": "horas", "day": "día", "days": "días", "week": "semana", "weeks": "semanas", "month": "mes", "months": "meses", "year": "año", "years": "años", "yesterday": "ayer", "tomorrow": "mañana", "now": "ahora", "ago": "hace", "in": "en" }` The following predefined locales are available. `$.easydate.locales.enUS` Please submit translations via email.

Public Functions

The following functions are not required to make use of EasyDate but are provided in case the functionality is needed.

$.easydate.pause( [selector] ): Pauses live updates of elements matching the given selector. If the selector argument is omitted then all updating will be paused.
$.easydate.resume( [selector] ): Resume live updates of paused elements matching the given selector. If the selector argument is omitted then all paused updating will be resumed.
$.easydate.set_now( date ): Makes all date calculations relative to the given date argument instead of the system clock. The date argument can be a Date object or a RFC 1123 valid timestamp string. When this function is called, all previously formatted dates will be re-adjusted to be accurate give the new "now". This is useful for synchronizing the system clock with a server-side clock.
$.easydate.get_now( ): Returns a Date object representing the current date. If $.easydate.set_now() has been called, this Date object is relative to the given date.
$.easydate.format_date( date [, options] ): Formats and returns the given date object. If the options argument is omitted, the default options are used.