Source

jQuery.localize /

Filename Size Date modified Message
5.2 KB
5.0 KB
277 B
4.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.

<time datetime="2010-11-12T13:14:15-00:00">12 November 2010</time>

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.

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

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