Source

jQuery.localize /

Filename Size Date modified Message
597 B
10.2 KB
5.1 KB
2.7 KB
3.4 KB
6.7 KB

jQuery.localize

jQuery plugin for localizing dates and times via the datetime attribute of the HTML5 <time> element.

Overview{id=overview}

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.

Requirements{id=requirements}

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.

Usage{id=usage}

$('time').localize()

Localize the elements in the provided jQuery object using the "default" settings.

$('time').localize(options)

Localize the elements in the provided jQuery object, favouring settings in the options hash over the "default" settings.

$('time').localize(format)

When passed a string (or function), the argument represents format. $('time').localize('yyyy/mm/dd') is shorthand for $('time').localize({format: 'yyyy/mm/dd'}).

$.localize(date, format)

Return date in the specified format.

$.localize(date)

Return date in the format specified by $.localize.format.

$.localize(format)

Return the current date in the specified format.

$.localize()

Return the current date in the format specified by $.localize.format.

$.localize.version

The plugin's version number.

Settings{id=settings}

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');

$.localize.abbrDays

Abbreviated day names.

Default: 'Sun Mon Tue Wed Thu Fri Sat'.split(' ')

$.localize.abbrMonths

Abbreviated month names.

Default: 'Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec'.split(' ')

$.localize.escaped

Determines the jQuery method -- text or html -- to which the generated string is passed. Set to true if the format string contains HTML.

Default: false

$.localize.format

Display format. See directives for more information.

Default: 'd mmmm yyyy'

$.localize.fullDays

Full day names.

Default: 'Sunday Monday Tuesday Wednesday Thursday Friday Saturday'.split(' ')

$.localize.fullMonths

Full month names.

Default: 'January February March April May June July August September October November December'.split(' ')

$.localize.ordinals

Ordinal dates (1st, 2nd, 3rd, etc.).

Default: Function with returns '1st' given 1, '2nd' given 2, etc.

$.localize.periods

AM/PM.

Default: ['AM', 'PM']

Directives{id=directives}

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)

Implicit and explicit formatting{id=disambiguation}

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.

Internationalization{id=i18n}

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'];

Custom functions{id=custom}

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.

Relative dates and times

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(' ');
      }
    }
  };
}());

Changelog{id=changelog}

0.7.1

  • 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.

0.7

  • Exposed formatting function (formerly formatDate) as jQuery.localize.

  • Changed the API for updating settings. Settings are now properties of jQuery.localize and can thus be updated via assignment.

    // 0.6
    $.fn.localize('o mmm')
    
    // 0.7
    $.localize.format = 'o mmm'
    
  • Changed the way in which the version number is accessed.

    // 0.6
    $.fn.localize.version
    
    // 0.7
    $.localize.version
    

0.6

  • 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 a jQuery object.

    // 0.5.1
    $().localize('load', 'o mmm')
    
    // 0.6
    $.fn.localize('o mmm')
    
  • Changed the way in which the version number is accessed.

    // 0.5.1
    $().localize('version')
    
    // 0.6
    $.fn.localize.version
    

0.5.1

  • Optimized internal pad function.

0.5

Updated the test suite to have it run against as many versions of jQuery as is feasible, and made optimizations which reduce the size of the minified code by more than 10%. No API changes.

0.4

Improved the source code's readability and made a handful of minor internal optimizations. No API changes.

0.3.5

  • Changed the way in which the test suite creates time elements to have it run in Internet Explorer.

0.3.4

  • Enabled the use of "☺" in format strings!

0.3.3

  • Renamed char variable chr to appease Closure Compiler.

0.3.2

  • Only <time> elements are now localized. Previously, any element with a datetime 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 a datetime attribute, the current time is used.

    // 0.3.1
    $('<time>').localize().attr('datetime') === undefined
    
    // 0.3.2
    $('<time>').localize().attr('datetime') !== undefined
    

0.3.1

  • Added escaped setting to allow format strings to contain HTML.

0.3

  • Streamlined API by mapping custom functions to format rather than custom, removing the need for special treatment.

    // 0.2
    $('time').localize('custom');
    
    // 0.3
    $('time').localize();
    

0.2

  • 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).

0.1

Initial release.