TimeZone

From Jsorm

Overview

TimeZone is a class providing the ability to calculate the actual calendar (or wall) time for a particular timezone at a given moment in time, taking into account timezone differences e.g. Moscow Standard Time is 2 hours ahead of Coordinated Universal Time (UTC), also known as Greenwich Mean Time (GMT). TimeZone will also account for daylight savings time, when it can. TimeZone also provides timezone support for the i18n Calendar class.

TimeZone recognizes three different types of timezones.

• Named: In named timezones, an official, recognized name of a location is provided. These are the standard names used by many computer systems, as well as the Java programming language, all based on the Elsie zoneinfo database. i18n also builds on the Elsie zoneinfo database, providing the zoneinfo files in a specialized format. The list of formal names is at Zoneinfo location names. If a named zone is used, all known changes in standard offsets, daylight savings time and short names (e.g. EST for New York City winter time) are used. In order for the named zone to function properly, the special zoneinfo files, distributed with jsorm i18n, must be in an appropriate location. TimeZone uses Ajax to retrieve the appropriate files.
• GMT: In GMT/UTC format, a time difference as an offset from GMT/UTC is provided. In the case of a GMT format, the offset from UTC is constantly the same. There is no consideration of daylight savings time or changes in standard offset. This can be in any of the following formats

• Local: If no timezone name is given, the current offset from UTC as given by the system that the library is running on, normally the client browser, is used. Like with GMT format, no consideration of changes in standard time or daylight time are taken into account.

Usage

To use TimeZone to retrieve information, first get a TimeZone object using JSORM.TimeZone.getZone(), then get the offset information for a particular moment in time using getZoneInfo() or getZoneInfoUTC(). Because getZone() must retrieve the zoneinfo information from the server via an asynchronous call (i.e. Ajax), getZone() returns no object. Rather, you need to pass it a callback in the config parameter that will receive the TimeZone object.

It is strongly recommended that you read the appropriate API documentation for JSORM.TimeZone.

var callback = function(success,zone,options) {
    if (success) {
        var info = zone.getZoneInfo(1970,0,0,0,0,0); // gets the zoneinfo for midnight at the beginning of 1970 in the local (wall) time, i.e. Los Angeles
        var otherInfo = zone.getZoneInfoUTC(28800000); // gets the zoneinfo for the moment of 28,800,000 milliseconds since system Epoch, i.e. midnight 1 January 1970 
    } else {
        alert('Could not process zone');
    }
}
 
var config = {callback: callback, name: 'Americas/Los_Angeles'};
JSORM.TimeZone.getZone(config);

The object returned from getZoneInfo() and getZoneInfoUTC() has three properties.

• offset is the offset in seconds from UTC.
• isDst is whether or not the zone is in daylight savings time at that moment. 0 indicates no DST, 1 indicates DST.
• abbr is the string indicating the short-form abbreviation for the name of the zone at that time.

Continuing the example above, both zone and zoneinfo will be as follows.

{offset: -28800, isDst: 0, abbr: "PST"}

Zoneinfo files

The zoneinfo files used in JSORM.TimeZone are a specially-formatted JSON-compiled version of the standard Elsie zoneinfo files. These files are created as part of the jsorm service. They are distributed as part of the entire jsorm i18n package, or can be downloaded separately. The updates closely follow the Elsie zoneinfo updates, and are not necessarily synchronized with jsorm i18n version updates.

The distribution should be unzipped and installed in a directory that is accessible to the client, for example, http://myserver/lib/zoneinfo/. By default, TimeZone assumes the files to be in /lib/i18n/zoneinfo/ on your server. The path is comprised of two elements: basepath and path. The two are appended to give the full path relative to the current file as basepath+path. If you wish to change the path to the zoneinfo files, you can do it one of two manners.

• Default: If you change TimeZone.path and TimeZone.basepath, all subsequent searches will use those paths. The default for basepath is /lib/, while the default for path is i18n/zoneinfo/.
• Individual: If you wish to override the default on a particular getZone() call, set the basepath and path properties of the config parameter to the desired paths.

The following gives an example of changing the default as well as an individual change.

// use the default of /lib/i18n/zoneinfo
var config = {callback: callback};
TimeZone.getZone(config);
 
// change the path for this call only
config.basepath = "./";
config.path = "newpath/";
TimeZone.getZone(config);
 
// change the default for all future calls
TimeZone.basepath = "/funnypath/"
TimeZone.path = "subfunnypath/";