Calendar

From Jsorm

Overview

Calendar is a class providing calendrical and time conversion and formatting functionality in JavaScript. It allows you to convert between any moment in absolute time, normally measured as milliseconds since the system Epoch, midnight at the beginning of 1 January 1970 GMT, and a localized time in any time zone and any calendar. Features include:

• Ability to convert between absolute UTC/GMT time and localized time in any time zone
• Ability to switch between time zones on the fly
• Ability to format a moment in time in multiple output formats
• Ability to change any one element, e.g. day of the month, and recalculate the rest
• Ability to add or remove units of time to any one element, e.g. day of the month, and optionally recalculate the rest
• Ability to use different calendaring systems

Usage

Getting a Calendar

In order to use a Calendar, you must first get a Calendar object via JSORM.calendar.getCalendar(config). The config must include:

• locale the name of the locale to use. To understand locale structures, see ResourceBundle.
• calendar the name of the calendar implementation to use, e.g. gregorian
• zone the name of a TimeZone to use or an already retrieved TimeZone object.
• date the initial date to set the calendar at or, if undefined/null, use right now
• callback the callback function to call when the Calendar is ready

Because the locale information and the calendar implementation, as well as possibly the TimeZone, are retrieved from the server asynchronously, via Ajax, calls to getCalendar() do not return the actual Calendar object. Instead, the callback passed to the getCalendar() call in the config parameter is called when the Calendar is ready.

The example below retrieves a Calendar that implements the Gregorian calendar, in the time zone of Australia/Sydney, using the locale US English, for 01:00 1 January 1970 UTC.

var cal;
var callback = function(success,calendar,options) {
    if (success)
        cal = calendar;
}
var config = {callback: callback, calendar: "gregorian", zone: "Australia/Sydney", locale: "en_US", date: new Date(3600000)};
JSORM.calendar.getCalendar(config);

Using Fields

The Calendar object sets all the fields necessary to get any part of the field. You can get or set any of them and then see how they affect others. There are two ways to get or set fields.

• Directly: Every Calendar object has a get() and set() method. When called, you can pass the string name of a field you wish to get/set and do so directly. The list of fields is included at the beginning of the JSORM.calendar class documentation in the API documentation.
• Indirectly: Many fields have special get/set methods, e.g. getYear() and getHourOfDay(). All are listed in the API documentation.

The following examples get and set various fields in various ways.

cal.get('YEAR'); // get the year
cal.getMonth(); // get the month
cal.setMonth(0); // set the month to January
cal.set('DATE',25); // set the date to 25, beginning at 0, thus the date is now January 26

It is important to remember that, unless explicitly listed otherwise in the API documentation, all fields run from 0 to their maximum. Thus, January in a Gregorian calendar is month 0 and December is month 11.

At any moment, we can get and set the absolute time, i.e. milliseconds since the system Epoch, midnight at the beginning of 1 January 1970 UTC.

cal.getTime();
cal.setTime(1234567890);

Rolling or Adding

In addition to directly setting or a field, you can increment or decrement the field by a fixed amount. When you do so, you might increment or decrement a field past its limit. FOr example, if the time is currently 8:00 in the morning (0800 in 24-hour time), and you add 23 hours, Calendar needs to know if you mean to change only the hour, i.e. it should now be 7:00am (0700) on the same day, or if you mean to change all impacted fields, i.e. it should now be 7:00am (0700) on the next day. The difference between these two is the difference between roll, which does not change other fields, and add, which does.

// ROLL EXAMPLE
// If calendar is currently set to 0800 on January 26
cal.getHourOfDay(); // returns 8
cal.getDate(); // returns 25
cal.roll('HOUR_OF_DAY',23);
cal.getHourOfDay(); // returns 7
cal.getDate(); // returns 25

// ADD EXAMPLE
// If calendar is currently set to 0800 on January 26
cal.getHourOfDay(); // returns 8
cal.getDate(); // returns 25
cal.roll('HOUR_OF_DAY',23);
cal.getHourOfDay(); // returns 7
cal.getDate(); // returns 26

Calculations

In order to be efficient, Calendar does not recalculate every time you set a field to a value. It recalculates only when you do one of the following:

• get() from any field (or the direct equivalents getYear(), getHourOfDay(), etc.)
• roll()
• add()
• setTime()

Formatting

Calendar can output its current date in its given time zone and locale in a string suitable for display to end-users. Calendar can display simple date, time or date-and-time formats, and it can support advanced formatting.

Basic Formatting

To output a basic format, simply use the time(), date() or dateTime() methods.

cal.time(); // returns "8:00:00AM"
cal.date(); // returns "Tuesday, February 19, 2008"
cal.dateTime(); // returns "Tuesday, February 19, 2008 8:00:00AM"

Note that the output will change based on the actual time (of course) and the defaults for the locale with which the calendar was initialized.

Advanced Formatting

Advanced formatting is supplied by the format() method of Calendar. To use it, you pass a formatting string and formatting style, and receive back a string output of the date formatted appropriately. Calendar currently supports the formatting strings of three styles: Java SimpleDateFormat, PHP Date and strftime().

The following examples show how to use advanced formatting.

// Java-style formatting
var style = JSORM.calendar.JAVA;
cal.format('yyyy.MM.dd G HH:mm:ss z',style); // returns "2008.02.19 AD 20:00:00 EST"
cal.format('EEE, d MMM yyyy HH:mm:ss Z',style); // returns "Tue, 19 Feb 2008 20:00:00 -0500"
cal.format('yyyy-MM-dd'T'HH:mm:ss.SSSZ',style); // returns "2008-02-19T20:00:00.765-0600"

// PHP-style formatting
var style = JSORM.calendar.PHP;
cal.format('l dS \of F Y h:i:s A',style); // returns "Tuesday 19th of February 2008 08:00:00 AM"
cal.format('l \\t\h\e jS',style); // returns "Tuesday the 19th"
cal.format('D M j G:i:s T Y',style); // returns "Tue Feb 19 08:00:00 EST 2008"

// strftime-style formatting
var style = JSORM.calendar.STRFTIME;
cal.format('%y-%d-%e %C %D',style); // returns "08-02-19 20 02/19/08"
cal.format('%Y-%B-%e',style); // returns "2008-February-19"
cal.format('%I %p',style); // returns "08:00 PM"

Please see the API documentation for more detail on using formatting, as well as the appropriate formatting style references: Java SimpleDateFormat, PHP date() and strftime().

Calendar Systems

Included Calendars

As of this writing, the following calendars are included with the distribution:

• Gregorian Calendar, used as a standard calendaring system by most countries in the world.
• Julian Calendar, predates the Gregorian calendar, but still used for the calculation of some holidays in Orthodox Churches.
• Hebrew Calendar, used by Jews and other religions or historians relying on the Hebrew or Christian Bible.
• Islamic Calendar, used by Muslims and other religions or historians relying on the Koran.
• ISO Calendar, which is simply a variant on the Gregorian calendar. For usage, see the section on the ISO Calendar.
• Sym010 Calendar, a very scientific calendar created by Dr. Irv Bromberg of the University of Toronto, available at [1].
• Sym454 Calendar, another very scientific calendar created by Dr. Irv Bromberg of the University of Toronto, available at [2].

Calendars in the works

Many other calendars are in the process of being developed, including Islamic, Julian, Coptic and many others.

Creating new calendars

jsorm i18n is modular; all calendar system implementations are loaded as modules via ajax. As such, it is possible to create and add on nearly any calendars, including calendars that do not exist in the world. To do so, please see the article creating calendars and the API documentation, specifically the class JSORM.CalendarImpl.