Clone this wiki locally
How to use the plugin
Using the plugin is incredibly easy. The simplest way is to include the plugin on the page you want to display a local time on after the main jQuery plugin:
And then every string that has a data-localtime-format tag that contains an ISO8601 formatted date/time string in UTC will be converted to the viewers local time when the page loads. For example,
will display in the viewers browser as
2010-12-12 11:27:00 if they are in the PST timezone,
2010-12-12 19:27:00 if they are in the UK, and
2010-12-12 14:27:00 in New York.
Note that from release 0.9.1 onwards, with the tag the value of the datetime attribute is used rather than the text in the tag. For example;
<time datetime="2011-01-03T13:39Z" data-localtime-format>Jan 3rd, 2011</time>
Changing the default format
You can specify the default format by calling the following immediately after the plugin has loaded:
Using formats other than the default
You can specify almost any format you like to display your time. For example,
<span data-localtime-format="dd MMM, yyyy HH:mm">2010-12-12T19:27:00Z</span>
<time datetime="2010-12-12T19:27:00Z" data-localtime-format="dd MMM, yyyy HH:mm">Dec 12th, 2010</time>
12 Dec, 2010 11:27 in California,
12 Dec, 2010 19:27 in the UK, and
12 Dec, 2010 14:27 in New York.
Alternatively, you can use CSS classes to specify the format. By default, the plugin uses the CSS class
localtime. For example,
will display in the viewers browser as
2010-12-12 11:27:00 in California, etc.
You can also specify different class names, for example:
Specifying the time
The element to be formatted must contain a string that is formatted using a subset of the W3C profile of the ISO 8601 date and time format. It must include the complete date as well as hours and minutes. Optionally, seconds and milliseconds can also be provided. Thus, the following are all valid dates that can be parsed:
As a convenience, space can also be used instead of "T" as the date/time separator:
Note that the only supported timezone is UTC (aka Zulu time), indicated by the trailing
Z which must be present.
This string can easily be generated in a number of different ways;
return gmdate('Y-m-d\TH:i:s.u\Z', time());
SET time_zone = 'UTC'; SELECT CONCAT(NOW(), 'Z');* Java:
SimpleDateFormat isoFormat = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS'Z'"); isoFormat.setTimeZone(TimeZone.getTimeZone("UTC"); return isoFormat.format( new Date() );* C#/VB.NET:
Formatting the time
Although the HTML source of the page is limited to the format of the time, the plugin supports a wide range of date/time formats - the default format is
The full list of supported format is as follows:
d- The day of the month. 1 to 31.
dd- The day of the month, padded to two characters with a leading zero if necessary. 01 to 31.
ddd- The first three letters of the day of the week, e.g. Mon.
ddddd- The full day of the month, e.g. Monday.
o- (the lower case letter o, not the number zero) - the ordinal abbreviations - i.e. st, nd, rd, or th, depending on the date.
M- The month of the year. 1 to 12.
MM- The month of the year, padded to two characters with a leading zero if necessary. 01 to 12.
MMM- The first three letters of the month name. Jan to Dec.
MMMMM- The full month name. January to December.
yy- The two digit year. 00 to 99.
yyyy- The four digit year. 0000 to 9999.
H- Hours (24 hour time, no leading zero). 0 to 23.
HH- Hours (24 hour time, leading zero). 00 to 23.
h- Hours (12 hour time, no leading zero). 1 to 12.
hh- Hours (12 hour time, no leading zero). 01 to 12.
a- AM/PM indicator. AM or PM.
t- AM/PM indicator (first letter). A or P.
tt- AM/PM indicator (full). AM or PM.
m- The minute of the hour. 0 to 59.
mm- The minute of the hour, padded to two characters with a leading zero if necessary. 00 to 59.
s- The second of the minute. 0 to 59.
ss- The second of the minute, padded to two characters with a leading zero if necessary. 00 to 59.
S- The millisecond of the second. 0 to 999.
SS- The millisecond of the second, padded to two characters. 00 to 999.
SSS- The millisecond of the second, padded to three characters. 000 to 999.
z- Timezone offset (hours only, no leading zero) - e.g. -8
zz- Timezone offset (hours only, leading zero) - e.g. -08
zzz- Timezone offset (full hours/minutes) - e.g. -08:00
Any other characters are passed as-is. If you want to pass a literal string, enclose that string in single quotes - e.g.
<span data-localtime-format="'The time is' HH:mm">2010-12-12T19:27:00Z</span>
The time is 19:27. To use a single quote as a literal, escape it using a backslash outside of the literal. For example
<span data-localtime-format="'It is' h 'o'\''clock'">2010-12-12T19:27:00Z</span>
which will display
It is 7 o'clock.
These date/time formatters are a combination of those in the SimpleDateFormat class in Java and those provided by the Globalize plugin. The original plan was to use the Java format strings for backward compatibility, and to implement the Globalize format strings to allow easier globalisation in the future. However, work on the Globalization plugin seems to have stalled (see also issue 2).
Programmatically formatting dates
If you want to format a date after the page has loaded, you can use the
toLocalTime method to format the date, using something like:
$.localtime.toLocalTime(utcTime, 'yyyy-MM-dd HH:mm');
Alternatively, you can call the
formatObject method to format a jQuery object whose text or value is a date, e.g.
$.localtime.formatObject($(this), 'yyyy-MM-dd HH:mm');
If you want to format a number of elements, then you can call, for example,
If no parameters are supplied, then the whole page is formatted. Be careful with this, though; this method is automatically called when the page is loaded, changing the content of elements requiring formatting. Calling it again may cause an error as those original elements may no longer contain an ISO8601 formatted date/time.