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 Feb 4, 2013 · 13 revisions

How to use the plugin

Introduction

Using the plugin is incredibly simple. Simple include the plugin on the page you want to display a localtime on after the main jQuery plugin;

<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"></script>
<script type="text/javascript" src="jquery.localtime-0.4.js"></script>
<script type="text/javascript">$.localtime.setFormat("yyyy-MM-dd HH:mm");</script>

And then every string that has a CSS class of "localtime" that contains an ISO 8601 date/time string will be converted to the viewers local time;

For example,

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

will display in the viewers browser as 2010-12-12 11:27 if they are in the PST timezone, 2010-12-12 19:27 if they are in the UK, and 2010-12-12 14:27 in New York.

Specifying different CSS classes

If you don't want to (or can't for some reason) use the CSS class named "localtime", then you can specify the name of the class you want to format with the style;

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

If you want two or more different styles, then simply specify them all;

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

Supported ISO 8601 formats

When specifying the time in the HTML source of the page, the plugin expects that time to be specified in UTC. The localtime display of that UTC time is calculated using the browser. The UTC time must be specified in one of a subset of the IS0 8601 formats, specifically;

  • yyyy-MM-dd HH:mmZ
  • yyyy-MM-dd HH:mm:ssZ
  • yyyy-MM-dd HH:mm:ss.SSSZ

Formatting details

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 for the date/time is yyyy-MM-dd HH:mm:ss - if you want to display it in any other format, then simply call $.localtime.setFormat(timeFormat); immediately after loading the plugin, where the timeFormat contains any of the following;

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

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 for the former to remain for backward compatibility, and implement all of the latter. However, work on the Globalization plugin seems to have stalled, so this is not currently scheduled (see also issue 2).

Programmatically formatting dates

If you are receiving an ISO8601 string back from an AJAX query, you can use the plugin to format that string using something like:

 jQuery.localtime.toLocalTime(utcTime, 'yyyy-MM-dd HH:mm');
Clone this wiki locally