michaelahlers / angular-timezones

AngularJS features for TimezoneJS-enhanced JavaScript Date objects.

Timezones for AngularJS

AngularJS features for TimezoneJS-enhanced JavaScript Date objects.

Deprecation Notice

This project will not receive additional features, bug fixes, or any other maintenance, and the project will be deleted on January 1, 2015. If you wish to continue development or work with more active projects where issues might be resolved, please see forks.

Inclusion

Bower

Bower users can add the following to their package dependencies. Be sure to see tags for a list of available versions.

{
  "dependencies" : {
    "angular-timezones" : "[email protected]:michaelahlers/angular-timezones.git#0.3.8"
  }
}

Usage

After including angular-timezones.js, add this package to your application.

var yourApplication = angular.module('your-application', ['Timezones'])

Configuration

This package provides the IANA timezone data, but you may have this resource served from a different location or you wish to provide your own data. To change that location, set the $timezones.definitions.location property to the appropriate path or URL.

yourApplication.constant('$timezones.definitions.location', '/custom/path/to/tz/data')

This is done by the unit tests and illustrated in docs/examples.

Resolution

The $timezones.resolve(timezone, reference) function will, using the reference Date provided, look up complete details about the timezone—including the abbreviation, offset, and decomposed region and locality. This is useful for avoiding clever tricks to extract abbreviations from Date.toString (which is not particularly portable or robust). Additionally, resulting values are derived from the authoritative IANA timezone data.

Detection

If jsTimezoneDetect is included, the $timezones.getLocal() function will detect the browser's local timezone and provide a complete definition that's resolved against the IANA database.

Examples

See docs/examples for demonstrations of these features. As timezone data (found in tz/data) must be served from a web server, these examples will not work from the local disk. However, there is a quick solution for most platforms: the files can be served with Python's SimpleHTTPServer.

python -m SimpleHTTPServer

Once running, visit http://localhost:8000/ in your web browser, and navigate to the examples folder.

Developers

Timezones for Angular is tested with Karma and PhantomJS against the latest available release of jQuery (2.0.0) and AngularJS (1.1.4).

With NPM installed, you can test your modifications with the following.

npm install
npm test

Acknowledgements

This project was originally forked from angular-timezone-js by Tomas Ruzicka.

Timezone data provided by IANA (extracted from tzdata2013c.tar.gz).

angular-timezones's Issues

License missing

I would like to use angular-timezones in my project, but I don't want to do a code theft. Could you add a license file or just a license info so that we know how could we use that library?

Document Parameterized Timezone Data URL

It is possible to load timezone files from alternate locations (this is especially important when using in nested paths), but the feature's currently undocumented. Refer to tzDateSpec.js for a current usage.

Resolve Complete Timezone Definition

Introduce a service method that can be used to resolve Olson names and abbreviations to complete timezone definitions objects that include (among other fields) the offset, printable label, abbreviation (e.g., EST, CDT). This will be useful to future additions, such as timezone pickers.

Comply with ECMA-262 §15.9.5.26

The $timezones.resolve function incorrectly inverts timezone offset values. This value is the difference between UTC and local time. If the offset is positive, the local time is behind UTC, and vice versa. See ECMA-262 §15.9.5.26 and Date.getTimezoneOffset.

Support the "Factory" Timezone

There is a rarely used, obscure timezone simply called "Factory" that acts as a synonym for GMT offset 0. Arthur David Olson describes it as follows.

For companies who don't want to put time zone specification in their installation procedures. When users run date, they'll get the message. Also useful for the "comp.sources" version.

This will require some special cases, but is so rarely used that we won't support or test for it now.

Replace full path in Bower dependencies with version only

With bower, installation is failing on Windows because of a full path being hard-coded in the list of dependencies:

The following:

{
  "dependencies" : {
    ...
    "timezone-js" : "[email protected]:mde/timezone-js.git#v0.4.4"
  }
}

should be replaced by something like (as other dependencies):

{
  "dependencies" : {
    ...
    "timezone-js" : "0.4.4"
  }
}

Testing locally it works like a charm.

Minification issue

Greetings!... i've been using this great module on a project without any problems, until i minified the app. I'm using $filter('tzAlign') but this gives

Error: [$injector:unpr] Unknown provider: aProvider <- a <- tzAlignFilter

The weird thing is that i inspected the minified js and the tzAlign filter is declared. Other filters like uppercase are working fine. I guess that ultimately i could use the unminified version of the module, at least no mangled, but i'm trying to reduce the load time of the app. So, what other solution may be?

Introduce Unit Tests

Some lightweight unit testing is appropriate, especially with some refactoring I'd like to do.

Follow AngularJS Conventions for Module Initialization

Make it easier to configure the timezone data sources, and track more closely with AngularJS module configuration guidelines.