Using timezonejs in an Aria Templates application


Playing with timezone in javascript can be problematic not because of the timezone offset calculation, which can easily be done with the getTimezoneOffset method of a date object, but because of the DST (daylight saving time) policy of the local countries/states.

Let’s take New York and Paris as an example. The official timezones for these two locations is UTC-5 and UTC+1, but because of the DST policy, the « real » New York time is UTC-5 before beginning of March and UTC-4 after. For Paris it’s UTC+1 till end of March then UTC+2 is used.

So if you have to convert a time from one timezone to another, you will need to know what are the local dates for both, depending their own rules, not with only their official UTC offsets.

The IANA Time Zone Database

An official and public database has been created to reference all the rules used over the world, for any moment in the history (don’t forget that the rules can change depending on politician decisions).

You will find on Wikipedia the detailed information about the tz database, which is the reference information for any language which wants to deal with the timezones.


Unlike some server side languages as Java or PHP, which have internally an API to get the timezones information, javascript can’t retrieve it with its own API.

The most known javascript library to deal with the timezone is timezonejs. Its open source code contains the IANA information, and it’s usage is better driven in two steps: the first one is to preprocess the database to a json, based on the timezones you plan to use, the second one is to load the library and the json on the client in order to use them.

Compile the IANA database to a json file

This process is done with nodejs, and is quite straitforward. node-preparse.js will be found in the src directory, and can be used with node to compile the information in the tzdata directory. For example, if you want to compile all the timezones, you can run the following command line from the src directory:

node node-preparse.js ../tzdata > tz.json

As a result, you will obtain the file tz.json that you will place on an acessible location of your server. Some optional syntax exists in order to generate a subset of the whole timezones.

Loading and using timezonejs in Aria Templates

Now you have timezonejs (in src/date.js, that you could rename timezonejs.js, for example) and your json information accessible on your server, it’s time to load it and use it in Aria Templates. Timezonejs doesn’t have a “transport” to get the json file (by default, timezonejs tries to use jquery if available).

This operation can be easily achieved in Aria templates, without using any third party:

aria.utils.ScriptLoader.load("aria/templates/timezone/timezonejs.js", {
  fn : function() {
    var tz = timezoneJS.timezone;
    tz.loadingScheme = tz.loadingSchemes.MANUAL_LOAD;

      url: '/aria-templates/test/aria/templates/timezone/tz.json',
      expectedResponseType: 'json',
      callback: {
        fn: function (result, args) {
          var json = aria.utils.Json;

          // Init timezonejs
          data = result.responseJSON;
          json.inject(data.zones, tz.zones);
          json.inject(data.rules, tz.rules);

          // Use it !
          var dt = new timezoneJS.Date(2013, 1, 15, 12, 0, 'America/New_York');
          json.setValue(, "newYork", dt.toString());
          json.setValue(, "paris", dt.toString());
        scope: this
  scope : this

The first step is to use aria.utils.ScriptLoader.load to load the library itself, and then aria.core.IO.asyncRequest is used with expectedResponseType: ‘json’ to get and evaluate the json. As a result, the json data are injected in timezonejs and the library is ready.

Now a new date can be created through timezoneJS.Date (note the extra timezone parameter in the previous code), and can be changed with the setTimezone method to finally get any local time according to the country rules.

One response on “Using timezonejs in an Aria Templates application

  1. Fabio Crisci Team Member
    on 8 April 2013, 4:00 pm

    It’s good to know that Microsoft managed to include DST in the specification for EcmaScript 6

    Well done

Leave a Reply

Your email address will not be published. Required fields are marked *