jQuery plugin for localizing dates and times via the datetime
attribute of
the HTML5 <time>
element.
Client-side JavaScript is capable of localizing dates and times on web pages
and in web applications. The HTML5 time
element encapsulates date,
time, and time zone information in an accessible manner, and its datetime
attribute provides a useful hook for JavaScript localization.
Localization is not possible without sufficient data. In order for a <time>
element to be localized, it must contain a datetime
attribute, and this
attribute's value must contain year, month, date, hours, minutes, and time
zone offset. Seconds are optional, and may include a fractional component.
<time datetime="2010-11-12T13:14:15+00:00">12 November 2010</time>
If passed a <time>
element without a datetime
attribute, the current
time is used.
Localize the elements in the provided jQuery
object using the "default"
settings.
Localize the elements in the provided jQuery
object, favouring settings
in the options
hash over the "default" settings.
When passed a string (or function), the argument represents format
.
$('time').localize('yyyy/mm/dd')
is shorthand for
$('time').localize({format: 'yyyy/mm/dd'})
.
Return date
in the specified format
. For convenience, date
may be the
number of milliseconds since the Unix epoch rather than a Date
object.
Return date
in the format specified by $.localize.format
. For convenience,
date
may be the number of milliseconds since the Unix epoch rather than a
Date
object.
Return the current date in the specified format
.
Return the current date in the format specified by $.localize.format
.
The plugin's version number.
Settings can be specified by passing an options
hash to $.fn.localize
.
$('time').localize({
abbrDays: 'Sun,Mon,Tues,Wed,Thurs,Fri,Sat'.split(','),
format: 'ddd o mmm yyyy'
});
In this case the provided options (abbrDays
and format
) will be used in
place of the corresponding defaults.
The defaults (which are properties of $.localize
) can be changed to avoid
repetition.
$.localize.abbrDays = 'Sun,Mon,Tues,Wed,Thurs,Fri,Sat'.split(',');
$.localize.format = 'ddd o mmm yyyy';
$.localize.periods = ['am', 'pm'];
$('.article-metadata time').localize();
$('.comment-metadata time').localize('h:MMa ddd o mmm yyyy');
Abbreviated day names.
Default: 'Sun Mon Tue Wed Thu Fri Sat'.split(' ')
Abbreviated month names.
Default: 'Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec'.split(' ')
Display format. See directives for more information.
Default: 'd mmmm yyyy'
Full day names.
Default: 'Sunday Monday Tuesday Wednesday Thursday Friday Saturday'.split(' ')
Full month names.
Default: 'January February March April May June July August September October November December'.split(' ')
The function called, with the localized date string as an argument, for each
element in the jQuery collection. Within the function, this
references the
jQuery-wrapped <time>
element.
If a format string contains HTML, a custom handler is necessary for it to be treated as such:
$('time').localize({
format: '<span>%d %mmmm %yyyy</span> <span>%h.%MM\u2009%a</span>',
handler: function (dateString) {
this.html(dateString);
}
});
Default: function (dateString) { this.text(dateString) }
Ordinal dates (1st, 2nd, 3rd, etc.).
Default: Function with returns '1st'
given 1
, '2nd'
given 2
, etc.
AM/PM.
Default: ['AM', 'PM']
yy: "Year in two digit form"
yyyy: "Year in full"
m: "Month in numeric form"
mm: "Month in numeric form, zero-padded"
mmm: "Month name, abbreviated"
mmmm: "Month name"
d: "Date"
dd: "Date, zero-padded"
ddd: "Day of the week, abbreviated"
dddd: "Day of the week"
o: "Date in ordinal form (1st, 2nd, 3rd, etc.)"
h: "Hours in 12-hour time"
hh: "Hours in 12-hour time, zero-padded"
H: "Hours in 24-hour time"
HH: "Hours in 24-hour time, zero-padded"
M: "Minutes"
MM: "Minutes, zero-padded"
s: "Seconds"
ss: "Seconds, zero-padded"
S: "Seconds with zero-padded milliseconds"
SS: "Seconds, zero-padded, with zero-padded milliseconds"
a: "Period (AM/PM)"
Z: "Time zone offset (e.g. +10:00)"
By default, all characters in a format string that can be matched to directives are replaced by the appropriate values. This keeps format strings short and readable.
Occasionally, one may wish to include literal characters which are normally
treated as directives. One might expect .localize('o of mmmm')
to result in
"15th of March" or similar. Instead, it'll give "15th 15thf March".
Directives can be specified explicitly to disambiguate in such cases. All
characters in a format string with one or more percent signs are treated
as literals unless preceded by a percent sign. '%%'
is output as "%".
.localize('%o of %mmmm')
will produce the desired result.
Sane defaults are provided for displaying dates and times in English, but these aren't much help if a page's content is in Japanese or Icelandic. Thankfully, non-English languages work equally well.
$.localize.format = '%d de %mmmm de %yyyy';
$.localize.fullDays = 'domingo,lunes,martes,miércoles,jueves,viernes,sábado'.split(',');
$.localize.fullMonths = ['enero', 'febrero', 'marzo', 'abril', 'mayo',
'junio', 'julio', 'agosto', 'septiembre',
'octubre', 'noviembre', 'diciembre'];
While format
is typically a string containing directives, it
may instead be a function that takes a Date
object (the local equivalent of
the element's datetime
string) and returns the text to be displayed.
One can create a custom function which returns relative dates and times ("30 seconds ago", "3 weeks from now", etc.).
$('time').localize(function () {
var
s = 1, m = 60 * s, h = 60 * m, d = 24 * h,
units = [s, m, h, d, 7 * d, 30 * d, 365 * d],
names = 'second minute hour day week month year'.split(' '),
round = Math.round;
return function (date) {
var
delta = round((date - new Date) / 1000) || -1,
suffix = delta < 0 ? (delta = Math.abs(delta), 'ago') : 'from now',
i = units.length, n, seconds;
while (i--) {
seconds = units[i];
if (!i || delta > seconds) {
n = round(delta / seconds);
return [n, n === 1 ? names[i] : names[i] + 's', suffix].join(' ');
}
}
};
}());
- Make COLON optional in time-zone offset strings, in accordance with HTML 5.1.
- Accept SPACE in place of LATIN CAPITAL LETTER T in
datetime
attribute values, in accordance with HTML 5.1.
- Restructured project. No code changes.
-
Removed
escaped
option in favour of a versatilehandler
option. -
jQuery.localize
may now be passed a Unix timestamp in place of aDate
object.
-
Translated source to CoffeeScript, considerably improving its readability. When minified and gzipped, the resulting JavaScript file is only slightly larger than its hand-optimized predecessor.
-
Fixed a bug which caused
jQuery.fn.localize
to ignore certain options passed to it.aec2f34
-
Fixed a bug affecting format strings with more than one escaped percent sign.
65ac913
- Optimized
jQuery.localize.ordinals
.
-
Changed the initial value of
jQuery.localize.abbrDays
for consistency with JavaScript's abbreviations.new Date('18 October 2011') // Tue Oct 18 2011 00:00:00 GMT-0700 (PDT)
Tuesday and Thursday are now abbreviated as "Tue" and "Thu", respectively.
-
Exposed formatting function (formerly
formatDate
) asjQuery.localize
. -
Changed the API for updating settings. Settings are now properties of
jQuery.localize
and can thus be updated via assignment.// 0.6.0 $.fn.localize('o mmm') // 0.7.0 $.localize.format = 'o mmm'
-
Changed the way in which the version number is accessed.
// 0.6.0 $.fn.localize.version // 0.7.0 $.localize.version
-
Changed the API for updating settings.
jQuery.fn.localize
must now be invoked directly, rather than via$().localize
. As a result, it's clear whether an invocation updates settings or acts upon ajQuery
object.// 0.5.1 $().localize('load', 'o mmm') // 0.6.0 $.fn.localize('o mmm')
-
Changed the way in which the version number is accessed.
// 0.5.1 $().localize('version') // 0.6.0 $.fn.localize.version
- Optimized internal
pad
function.
-
Updated the test suite to have it run against as many versions of jQuery as is feasible.
-
Reduced the size of the minified code by more than 10%.
-
Improved the source code's readability.
-
Minor internal optimizations.
- Changed the way in which the test suite creates
time
elements to have it run in Internet Explorer.
- Enabled the use of "☺" in format strings!
- Renamed
char
variablechr
to appease Closure Compiler.
-
Only
<time>
elements are now localized. Previously, any element with adatetime
attribute would be localized. -
An element is no longer required to have a
datetime
attribute in order to be localized. If passed a<time>
element without adatetime
attribute, the current time is used.// 0.3.1 $('<time>').localize().attr('datetime') === undefined // 0.3.2 $('<time>').localize().attr('datetime') !== undefined
- Added
escaped
setting to allow format strings to contain HTML.
-
Streamlined API by mapping custom functions to
format
rather thancustom
, removing the need for special treatment.// 0.2.0 $('time').localize('custom'); // 0.3.0 $('time').localize();
-
Added support for custom functions (and by extension relative dates and times).
-
Added support for time zones other than UTC in
datetime
strings. -
Liberalized regular expression to accommodate
datetime
strings which include fractional seconds. -
Added directives for seconds with milliseconds (
S
) and zero-padded seconds with milliseconds (SS
).
Initial release.