jQuery Calendars Reference

The calendars plugin provides generic support for a number of world calendars. In general a calendar defines a series of years, each of which consists of a number of months that are then broken down into days. Days may also be grouped into weeks.

Each calendar implementation defines what the year sequence is (many have no year zero), how many months per year (varies in the Hebrew calendar), and how many days per month. Alongside this are the month and day names and localised values such as date format and start of the week.

Since JavaScript only supports the Gregorian calendar in its native Date object, a new date object with more generic calendar support is included within the plugin.

The calendars plugin is broken up into a series of modules to allow you to choose just the functionality you require.

The base module provides basic date and calendar support and includes an implementation of the Gregorian calendar.

Initial access is via the $.calendars variable. It offers the following functions:

var gc = $.calendars.instance();
var pc_fa = $.calendars.instance('persian', 'fa');

var d = $.calendars.newDate(2009, 1, 26);
var d = $.calendars.newDate(1388, 1, 1, 'persian', 'fa');
var d = $.calendars.newDate(1388, 1, 1, pc_fa);

digits: $.calendars.substituteDigits(
	['٠', '١', '٢', '٣', '٤', '٥', '٦', '٧', '٨', '٩']),

digits: $.calendars.substituteChineseDigits(
	['〇', '一', '二', '三', '四', '五', '六', '七', '八', '九'],
	['', '十', '百', '千']),

The following attributes are defined:

$.calendars.calendars.gregorian = GregorianCalendar;

JulianCalendar.prototype = new $.calendars.baseCalendar;

$.calendars.regional['fr'] = {
	invalidCalendar: 'Le calendrier {0} n\'a pas trouvé',
	invalidDate: 'Date {0} inadmissible',
	invalidMonth: 'Mois {0} inadmissible',
	invalidMonth: 'Année {0} inadmissible',
	differentCalendars: 'Ne peut pas utiliser {0} avec {1}'};

$.calendars.local = $.calendars.regional['fr'];

Regional Settings

Since JavaScript only supports the Gregorian calendar in its native Date object, a new date object with more generic calendar support is included within the base module: CDate.

This date object is always associated with a particular calendar and is generally created through it.

Many of the date functions return the date itself so that further calls can be chained together. It offers the following functions:

add | calendar | compareTo | date | day | dayOfWeek | dayOfYear | daysInMonth | daysInYear | epoch | extraInfo | formatYear | fromJD | fromJSDate | leapYear | month | monthOfYear | newDate | set | toJD | toJSDate | toString | weekDay | weekOfYear | year

var date1 = date.newDate(); // Clone
var date2 = date.newDate(2010, 1, 26);

var y = date.year();
date.year(2008);

var m = date.month();
date.month(2);

var d = date.day();
date.day(29);

date.date(2004, 1, 26);

if (date.leapYear()) ...

var e = date.epoch();

var fy = date.formatYear();

var moy = date.monthOfYear();

var woy = date.weekOfYear();

var diy = date.daysInYear();

var doy = date.dayOfYear()

var dim = date.daysInMonth();

var dow = date.dayOfWeek();

if (date.weekDay()) ...

var ei = date.extraInfo();
alert(ei.tzolkinDayName);

date.add(1, 'w');
date.add(-18, 'm');
date.add(1, 'y').add(1, 'd');

date.set(2010, 'y');
date.set(1, 'm').set(16, 'd');

if (date.compareTo(date2) == -1) ...

var c = date.calendar();

var jd = date.toJD();

var date2 = date.fromJD(jd);

var jsd = date.toJSDate();

var date2 = date.fromJSDate(jsd);

alert(date.toString());

All the calendar implementations within this plugin offer the same functionality, providing basic information about the calendar and generating and manipulating dates from that calendar.

add | dayOfWeek | dayOfYear | daysInMonth | daysInWeek | daysInYear | epoch | extraInfo | formatYear | fromJD | fromJSDate | fromMonthOfYear | isValid | leapYear | monthsInYear | monthOfYear | newDate | set | toJD | toJSDate | today | weekDay | weekOfYear

var d = gc.newDate(2009, 1, 26);
var d2 = gc.newDate(d);
var d = pc.newDate(1388, 1, 1);

var d = gc.today();

if (gc.leapYear(d)) ...
if (hc.leapYear(5768)) ...

var e = gc.epoch(d);
var e = pc.epoch(1388);

var fy = gc.formatYear(d);
var fy = mc.newDate(5160);

var m = gc.monthsInYear(d);
var m = hc.monthsInYear(5768); // = 13

var moy = gc.monthOfYear(d);
var moy = hc.monthOfYear(5768, 7); // = 1

var m = gc.fromMonthOfYear(y, o);

var woy = gc.weekOfYear(d);
var woy = pc.weekOfYear(1388, 1, 1);

var diy = gc.daysInYear(d);
var diy = hc.daysInYear(5768);

var doy = gc.dayOfYear(d);
var doy = pc.dayOfYear(1388, 1, 1);

var dim = gc.daysInMonth(d);
var dim = pc.daysInMonth(1388, 12);

var diw = gc.daysInWeek();

var dow = gc.dayOfWeek(d);
var dow = pc.dayOfWeek(1388, 1, 1);

if (gc.weekDay(d)) ...
if (pc.weekDay(1388, 1, 1)) ...

var ei = hc.extraInfo(d);
var ei = mc.extraInfo(5160, 1, 1);
alert(ei.tzolkinDayName);

gc.add(d, 1, 'w');
gc.add(d, 18, 'm');

gc.set(d, 2010, 'y');
pc.set(d, 1, 'm');

if (gc.isValid(2009, 1, 26)) ... // true
if (gc.isValid(2009, 2, 29)) ... // false

var jd = gc.toJD(d);
var jd = pc.toJD(1388, 1, 1);

var d = gc.fromJD(jd);

var jsd = gc.toJSDate(d);
var jsd = pc.toJSDate(1388, 1, 1);

var d = gc.fromJSDate(jsd);
var d = pc.fromJSDate(new Date(2009, 1 - 1, 26));

All the calendar implementations within this plugin offer the same functionality, providing basic information about the calendar and generating and manipulating dates from that calendar.

Regional Settings

digits: $.calendars.substituteDigits(
	['٠', '١', '٢', '٣', '٤', '٥', '٦', '٧', '٨', '٩']),

Several world calendars are implemented within this plugin. Details about their implementation are shown below.

Coptic | Discworld | Ethiopian | Gregorian | Hebrew | Islamic | Julian | Mayan | Nanakshahi | Nepali | Persian | Taiwan | Thai | Umm al-Qura

Gregorian Calendar

This is the proleptic Gregorian calendar that extends the normal Gregorian calendar back to dates before it was introduced on 15 October 1582 CE. It is the internationally accepted civil calendar. Points to note are:

• This is a solar arithmetical calendar.
• There is no year zero. 1 BCE (-1) was followed by 1 CE (+1).
• Leap years happen on years divisible by four, except those also divisible by 100, unless a multiple of 400. Negative leap years are offset by one due to the absence of year zero, i.e. 1 BCE is a leap year.
• Each year has 12 months of between 28 and 31 days and 365 or 366 days in total.
• The first day of the week is Sunday.
• 1 January 0001 CE has a Julian day number of 1721425.5 and corresponds to 3 January 0001 AD.

Taiwan Calendar

This is the Taiwanese calendar, which is identical to the Gregorian calendar except in its year numbering. It is used in the Republic of China (ROC). Points to note are:

• This is a solar arithmetical calendar.
• There is no year zero. 1 BROC (-1) was followed by 1 ROC (+1).
• Leap years happen on the corresponding Gregorian leap years.
• Each year has 12 months of between 28 and 31 days and 365 or 366 days in total.
• The first day of the week is Monday.
• 1 January 0001 ROC has a Julian day number of 2419037.5 and corresponds to 1 January 1911 CE.

Thai Calendar

This is the Thai calendar, which is identical to the Gregorian calendar except in its year numbering. It is used in Thailand. Points to note are:

• This is a solar arithmetical calendar.
• There is no year zero. 1 BBE (-1) was followed by 1 BE (+1).
• Leap years happen on the corresponding Gregorian leap years.
• Each year has 12 months of between 28 and 31 days and 365 or 366 days in total.
• The first day of the week is Sunday.
• 1 January 0001 BE has a Julian day number of 1523098.5 and corresponds to 1 January 0543 BCE.

Julian Calendar

This is the proleptic Julian calendar that extends the normal Julian calendar to dates outside its actual use. It was widely used from 1 AD until 1582 AD when it was replaced by the Gregorian calendar. Points to note are:

• This is a solar calendar.
• There is no year zero. 1 BC (-1) was followed by 1 AD (+1).
• Leap years happen on years divisible by four. Negative leap years are offset by one due to the absence of year zero, i.e. 1 BC is a leap year.
• Each year has 12 months of between 28 and 31 days and 365 or 366 days in total.
• The first day of the week is Sunday.
• 1 January 0001 AD has a Julian day number of 1721423.5 and corresponds to 30 December 0001 BCE.

Persian Calendar

This is the Persian calendar, also known as the Jalali or Iranian calendar. It is used in Iran, Afganistan, and related societies. Points to note are:

• This is a solar calendar.
• There is no year zero. 1 BP (-1) was followed by 1 AP (+1).
• Leap years follow a 33-year cycle (occaisionally 29- or 37-year cycles).
• Each year has 12 months of between 29 and 31 days and 365 or 366 days in total.
• The first day of the week is Shambe (Saturday).
• 1 Farvardin 0001 AP has a Julian day number of 1948320.5 and corresponds to 22 March 0622 CE (19 March 0622 AD).

Islamic Calendar

This is the Islamic calendar using the '16 civil' version, also known as the Hijri calendar. It is used in many Muslim countries. Points to note are:

• This is a lunar calendar.
• There is no year zero. 1 BH (-1) was followed by 1 AH (+1).
• Leap years follow a 30 year cycle.
• Each year has 12 months of between 29 or 30 days and 354 or 355 days in total.
• The first day of the week is Yawm As-sabt (Saturday).
• 1 Muharram al Haram 0001 AH has a Julian day number of 1948439.5 and corresponds to 19 July 0622 CE (16 July 0622 AD).

Umm al-Qura Calendar

This is the Umm al-Qura calendar, also known as the Saudi calendar. It is used in many Muslim countries and is very similar to the Islamic calendar. It was written by Amro Osama. Points to note are:

• This is a lunar calendar based on sightings.
• It is only valid for dates in the years 1357 to 1500 AH.
• Leap years follow a 30 year cycle.
• Each year has 12 months of between 29 or 30 days and 354 or 355 days in total.
• The first day of the week is Saturday.

Hebrew Calendar

This is the civil Hebrew calendar. It is used by Jews and followers of Judaism. Points to note are:

• This is a lunisolar calendar.
• There is no year zero. 1 BAM (-1) was followed by 1 AM (+1).
• Leap years follow a 19 year cycle.
• Each year has 12 or 13 months months of 29 or 30 days and 353, 354, 355, 383, 384, or 385 days in total.
• Year number changes at month 7 (Tishrei).
• The first day of the week is Yom Rishon (Sunday).
• 1 Tishrei 0001 AM has a Julian day number of 347997.5 and corresponds to 7 September 3761 BCE (7 October 3761 BC).
• extraInfo returns an explanation of the year type in yearType.

Ethiopian Calendar

This is the Ethiopian calendar. It is identical to the Coptic calendar except in its year numbering. It is used in Ethiopia and surrounding countries. Points to note are:

• This is a solar calendar.
• There is no year zero. 1 BEE (-1) was followed by 1 EE (+1).
• Leap years occur every four years on the third year of a cycle.
• Each year has 12 months of 30 days and an intercalary month of 5 or 6 days, making 365 or 366 days in total.
• The first day of the week is Ehud (Sunday).
• 1 Meskerem 0001 EE has a Julian day number of 1724220.5 and corresponds to 29 August 0008 CE (27 August 0008 AD).

Coptic Calendar

This is the Coptic calendar. It is identical to the Ethiopian calendar except in its year numbering. It is used in Egypt. Points to note are:

• This is a solar calendar.
• There is no year zero. 1 BAM (-1) was followed by 1 AM (+1).
• Leap years occur every four years on the third year of a cycle.
• Each year has 12 months of 30 days and an intercalary month of 5 or 6 days, making 365 or 366 days in total.
• The first day of the week is Tkyriaka (Sunday).
• 1 Thout 0001 AM has a Julian day number of 1825029.5 and corresponds to 29 August 0284 CE (27 August 0284 AD).

Nepali Calendar

This is the Nepali calendar, also known as Vikram Samvat. It is used in Nepal and Northern India. It was written by Artur Neumann. Points to note are:

• It uses lunar months and solar sidereal year.
• It is only exact for dates in the years 1970 to 2100 ABS.
• There is no year zero. 1 BBS (-1) was followed by 1 ABS (+1).
• Each year has 12 months of 29 to 32 days.
• The first day of the week is Sombaar (Monday).
• 1 Baisakh 0001 ABS has a Julian day number of 1700709.5 and corresponds to 14 April 57 BCE.

Nanakshahi Calendar

This is the Nanakshahi calendar, a calendar for the Sikh community. Points to note are:

• This is a tropical solar calendar.
• There is no year zero. 1 BN (-1) was followed by 1 AN (+1).
• Leap years happen on the corresponding Gregorian leap years.
• Each year has 12 months of either 30 or 31 days and 365 or 366 days in total.
• The first day of the week is Sunday.
• 1 January 0001 AN has a Julian day number of 2257673.5 and corresponds to 14 March 1469 CE.

Mayan Calendar

This is the Mayan Long Count calendar used by the Maya civilization of pre-Columbian Mesoamerica. Points to note are:

• This is an arithmetical calendar.
• There is a year zero.
• Years are grouped into repeating cycles based on the number 20.
• Each year has 18 months of 20 days being 360 days in total.
• Days and months number from 0.
• 0.0.0.0.0 has a Julian day number of 584282.5 and corresponds to 11 August 3114 BCE (6 September 3114 BC).
• extraInfo returns the Tzolkin date details in tzolkinDayName, tzolkinDay, and tzolkinTrecena, and the Haab date details in haabMonthName, haabMonth, and haabDay.
• Adds the forYear function to convert from the formatted year back to a sequential number.

Discworld Calendar

This is the Unseen University's Discworld calendar, used in the fictional Discworld in the books by Terry Pratchett. Points to note are:

• This is unlike other calendars.
• This is the Unseen University's counting of years.
• There is no year zero. 1 BUC (-1) was followed by 1 UC (+1).
• There are no leap years.
• Each year has 13 months of 16 or 32 days and is 400 days in total.
• The first day of the week is Monday and there are eight days in a week.
• There is no direct correspondence in dates so 1 Ick 0001 UC was chosen to have a Julian day number of 1721425.5 and corresponds to 1 January 0001 CE.
• extraInfo returns the name of the century in century.

The plus module adds extra functionality to CDate.

var f = d.formatDate();
var f = d.formatDate('yyyy-mm-dd');

The plus module adds extra functionality to calendars.

determineDate | formatDate | parseDate

var f = gc.formatDate('yyyy-mm-dd', date);
var f = gc.formatDate(
	'\'day\' d \'of\' MM \'in the year\' yyyy', date,
	{monthNames: ['1st month', '2nd month', ...]});

var date = gc.parseDate('yyyy-mm-dd', '2009-01-26');
var date = gc.parseDate(
	'\'day\' d \'of\' MM \'in the year\' yyyy',
	'day 26 of 1st month in the year 2009',
	{monthNames: ['1st month', '2nd month', ...]});

var date = gc.determineDate(+2);
var date = gc.determineDate('+2y -3w',
	gc.newDate(2001, 1, 1));
var date = gc.determineDate('2004-01-26',
	gc.newDate(2001, 1, 26), 'yyyy-mm-dd');

This module also adds several predefined date formats to the calendars:

Several error messages used during parsing and formatting are added to the global regional settings.