Skip to content
This repository has been archived by the owner on Aug 16, 2022. It is now read-only.

Usage

Jump to bottom
GregDThomas edited this page Jan 11, 2014 · 13 revisions

How to use the plugin

Introduction

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:

<script type="text/javascript" src="//ajax.googleapis.com/ajax/libs/jquery/1.3.0/jquery.min.js"></script>
<script type="text/javascript" src="jquery.localtime-0.9.1.min.js"></script>

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,

<span data-localtime-format>2010-12-12T19:27:00Z</span>

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:

<script type="text/javascript">$.localtime.setFormat("dd MMM, yyyy HH:mm");</script>

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>

or

<time datetime="2010-12-12T19:27:00Z" data-localtime-format="dd MMM, yyyy HH:mm">Dec 12th, 2010</time>

will display 12 Dec, 2010 11:27 in California, 12 Dec, 2010 19:27 in the UK, and 12 Dec, 2010 14:27 in New York.

Alternate usage

Alternatively, you can use CSS classes to specify the format. By default, the plugin uses the CSS class localtime. For example,

<span class="localtime">2010-12-12T19:27:00Z</span>

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:

<script type="text/javascript">$.localtime.setFormat( {dateAndTime: "yyyy-MM-dd HH:mm", dateOnly: "yyyy-MM-dd"});</script>

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:

  • 2013-02-17T16:50Z
  • 2012-11-01T08:60:13Z
  • 2011-08-05T23:11:51.345Z

As a convenience, space can also be used instead of "T" as the date/time separator:

  • 2013-02-17 16:50Z
  • 2012-11-01 08:60:13Z
  • 2011-08-05 23:11:51.345Z

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;

  • PHP: 
    return gmdate('Y-m-d\TH:i:s.u\Z', time());
* MySQL: 
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: 
return DateTime.Now.ToString("u");

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 yyyy-MM-dd HH:mm:ss.

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>

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

In either case, the date can either be a JavaScript Date object or a supported ISO8601 style string. If a format string is not supplied, the default format will be used.

If you want to format a number of elements, then you can call, for example,

$.localtime.format('#newDiv');

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.

Clone this wiki locally