My favorites | Sign in
Project Home Downloads Wiki Issues Source
Search
for
Usage  
How to use the plugin
Updated Apr 22, 2011 by greg.d.t...@gmail.com

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 jQuery Global plugin. The former remain for backward compatibility, those for the latter will eventually all be implemented (see also  issue 5 ).

Comment by gek...@gmail.com, Mar 21, 2012

Hi is there a way to trigger this for elements that were created with ajax?

Comment by olivier....@gmail.com, Sep 3, 2012

Hi,

Just added the possibility to locally change format, by specifying attribute data-localtime-format in the tag. Just modify the localise function like this :

    var localise = function () {
        var local_format = jQuery(this).attr('data-localtime-format');
        if (jQuery(this).is(":input")) {
            jQuery(this).val(jQuery.localtime.toLocalTime(jQuery(this).val(), local_format != undefined ? local_format : format));
        } else {
            jQuery(this).text(jQuery.localtime.toLocalTime(jQuery(this).text(), local_format != undefined ? local_format : format));
        }
    };

I'm using this to display a list of formatted dates/times for user to choose which he prefers to use (in his own settings). Hope it helps someone.

Comment by sereb...@gmail.com, Sep 26, 2012

Here is the way to localize HTML got wish ajax globally:

  jQuery(function($) {
     function localizeText(textValue) {
        var format;
        var localise = function () {
            if (jQuery(this).is(":input")) {
                jQuery(this).val(jQuery.localtime.toLocalTime(jQuery(this).val(), format));
            } else {
                jQuery(this).text(jQuery.localtime.toLocalTime(jQuery(this).text(), format));
            }
        };
        var formats = jQuery.localtime.getFormat();
        var cssClass;
        for (cssClass in formats) {
            if (formats.hasOwnProperty(cssClass)) {
                format = formats[cssClass];
                //convert text to jQuery var 
                var result = $(textValue);
                result.find("." + cssClass).each(localise);
                var text = "";
                //convert jQuery var back to text  
                $(result).each(function(index){
                    if (this.nodeName.toLowerCase() == 'script') {
                        text += '<script type="text/javascript">'+$(this).html()+"</"+"script>";
                    } else if (this.nodeType !== 1) {
                        //skip non-elements (HTML comments, text, etc)
                        return;
                    } else {
                        text += $(this).appendTo('<div>').parent().html();
                    }
                });
                return text;
            }
        }
        return textValue;
     }
     $.ajaxPrefilter(function(options, originalOptions, jqXHR) {
        var success = options.success;
        options.success = function(data, textStatus, jqXHR) {
            // override success handling
            //better to check if options.dataType -> "html"
            data = localizeText(data);
            if(typeof(success) === "function") return success(data, textStatus, jqXHR);
        };
    });
  });
Comment by SmoAutom...@gmail.com, Oct 23, 2012

hi

does this script converts the past EST time like (10/12/2012 20:00:00 EST) to the user time zone in PST (10/12/2012 17:00:00 EST)

Comment by jp.mar...@gmail.com, Oct 26, 2012

Thanks Greg for a nice plugin - it is useful. I have the same question as one of the persons above: Is there a way to execute this function outside of the jQuery event ready ?

Comment by project member greg.d.t...@gmail.com, Jan 17, 2013

Apologies for the lack of response; I had naively assumed that Google would email if someone added something on a project I'd created; it seems they don't - I only noticed this when I came back to it myself!

Anyway, @SmoAutomationService? - no. To get the plugin to work you have to specify the time in UTC. The browser will then convert that to whatever the local time is for that browser.

@jp.marple, @gekong - you can call jQuery.localtime.toLocalTime(UTCtime, jQuery.localtime.getFormat('classname')) as part of your AJAX query; that will convert a UTC string in to the format for the indicated class (or alternatively just supply the format that you want in the second param).

@olivier.cecillon - thanks, that looks really useful and probably a better mechanism overall than the one I used! That will get implemented in the trunk soon.

Comment by Sameh.Pi...@gmail.com, Aug 10, 2014

0x800a138f - JavaScript? runtime error: Unable to get property 'getFormat' of undefined or null reference ?? {Please help}

Comment by project member greg.d.t...@gmail.com, Aug 11, 2014

Hi Sameh; I need a bit more to go on; can you raise an issue at https://code.google.com/p/jquery-localtime/issues/entry, and ideally link to a page that is demonstrating this problem?

Thanks, Greg


Sign in to add a comment
Powered by Google Project Hosting