jQuery.localize /

Filename Size Date modified Message
276 B
9.1 KB
6.8 KB
277 B
7.2 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 object over the "default" settings.

$('time').localize(format)

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

$().localize('load', options)

Sometimes applying the same formatting to all <time> elements is not appropriate. Perhaps times are displayed alongside comment dates but not post dates. In such situations it's possible to avoid repetition by overriding the defaults for all future calls to localize.

$().localize('load', {
    format: 'yyyy/mm/dd',
    periods: ['a.m.', 'p.m.']
});

Note that "load" can be called on an empty jQuery object (and should, for the sake of clarity, since it doesn't act upon the elements provided).

$().localize('load', format)

As with regular calls to localize, "load" accepts the format string shorthand.

$().localize('version')

Returns the plugin's version number.

Settings{@id=settings}

Settings can be specified by passing an options object to localize.

$('time').localize({
    abbrDays: 'Sun Mon Tue Wed Thu Fri Sat'.split(' '),
    format: 'ddd o mmm yyyy'
});

In this case the options provided (abbrDays and format) will be used in place of the corresponding defaults.

abbrDays

Abbreviated day names.

Default: 'Sun Mon Tues Wed Thurs Fri Sat'.split(' ')

abbrMonths

Abbreviated month names.

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

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

format

Display format. See directives for more information.

Default: 'd mmmm yyyy'

fullDays

Full day names.

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

fullMonths

Full month names.

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

ordinals

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

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

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('load', {
    format: '%d de %mmmm de %yyyy',
    fullDays: 'domingo lunes martes miércoles jueves viernes sábado'.split(' '),
    fullMonths: 'enero febrero marzo abril mayo junio julio ' +
                'agosto septiembre octubre noviembre diciembre'.split(' ')
});

Custom functions{@id=custom}

It's possible to provide a function which receives a date and returns the text to be displayed. This is either passed to localize directly or "loaded" for later use.

// invoke immediately
$('time').localize(fn);

// "load" for later use
$().localize('load', fn);
// sometime later...
$('time').localize();

Within custom functions, this references the current jQuery instance. Custom functions are passed one or more arguments, the first of which is a Date object (the local equivalent of the element's datetime string).

Passing additional arguments to custom functions

$('time').localize(fn, arg1, ..., argN);

Arguments beyond the first passed to localize are handed on to the custom function. To pass arguments to a "loaded" custom function, set the first argument to null.

$('time').localize(null, arg1, ..., argN);

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.getTime() - (new Date()).getTime()) / 1000) || -1,
            suffix = delta < 0 ? (delta = Math.abs(delta), 'ago') : 'from now',
            i = units.length, n;

        while (i--) {
            if (!i || delta > units[i]) {
                n = round(delta / units[i]);
                return [n, n == 1 ? names[i] : names[i] + 's', suffix].join(' ');
            }
        }
    };
}());

Changelog{@id=changelog}

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.

Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.