A jQuery plugin that provides implementations of various world calendars and additional functionality such as conversion between calendars, parsing and formatting dates, and a datepicker. If you find this plugin useful please vote for it on the jQuery site.
This page provides a documentation reference for working with the plugin v1.1.1. Documentation on the datepicker is available separately. Download a copy for your own reference - just add jQuery JavaScript for full functionality.
See a demonstration of the calendars plugin or the associated datepicker and download the code from there. Or see a minimal page that you could use as a basis for your own investigations.
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.
| Module | Purpose | Dependencies |
|---|---|---|
| jquery.calendars.js | Base calendar support, including custom
CDate object and
Gregorian calendar. |
- |
| jquery.calendars.taiwan.js | Taiwanese calendar
support - also known as the Minguo calendar. Since 1.1.0. |
Base |
| jquery.calendars.thai.js | Thai calendar
support. Since 1.1.0. |
Base |
| jquery.calendars.julian.js | Julian calendar implementation. | Base |
| jquery.calendars.persian.js | Persian calendar implementation - also known as Iranian or Jalali calendar. | Base |
| jquery.calendars.islamic.js | Islamic calendar implementation - the 'civil 16' version. | Base |
| jquery.calendars.hebrew.js | Hebrew (civil) calendar implementation. | Base |
| jquery.calendars.ethiopian.js | Ethiopian calendar
support. Since 1.1.0. |
Base |
| jquery.calendars.coptic.js | Coptic calendar
support. Since 1.1.0. |
Base |
| jquery.calendars.mayan.js | Mayan (Long Count) calendar implementation. | Base |
| jquery.calendars.plus.js | Additional calendar functionality, such as parsing and formatting dates. | Base |
| jquery.calendars.picker.js | A datepicker with full calendar support and localisation. See separate documentation. | Base, Plus |
| jquery.calendars.picker.ext.js | Datepicker extensions with alternate renderers and added functionality. | Base, Plus, Picker |
| jquery.calendars.all.js | Combines the base, plus, and datepicker modules into one. | - |
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:
| Signature | Returns | Comments |
|---|---|---|
| $.calendars.instance(name, language) | *Calendar object | Retrieve a specific calendar implementation.name (string, optional) is the name of the calendar to find.
Implementations for the following calendars are available by including the
appropriate calendars module:
'gregorian', 'julian', 'persian', 'islamic', 'hebrew', 'ethiopian', 'coptic', 'mayan'.
If not specified a Gregorian calendar is returned.language (string, optional) is the language code for
a localisation pack for this calendar. It defaults to English.var gc = $.calendars.instance();
var pc_fa = $.calendars.instance('persian', 'fa'); |
| $.calendars.newDate(year, month, day, calendar, language) | CDate object | Create a new date object.
An error is thrown if the date is not valid for the calendar.
You can also create dates from a
calendar or from
another date.year (CDate) is a date to clone or
(number) is the year for the date.month (number) is the month for the date.
Omit if year is a date object.day (number) is the day for the date.
Omit if year is a date object.calendar (*Calendar,
optional) is the calendar to use for this date, or (string) the name of
the calendar (see above). If not specified a Gregorian calendar is used.
If year is a date object its calendar is used instead.language (string, optional) is the language code for
a localisation pack for this calendar. It defaults to English.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); |
The following attributes are defined:
| Name | Type | Default | Comments |
|---|---|---|---|
| calendars | object | - | This attribute provides direct access to the various
calendar implementations.
Each calendar adds its implementation "class" to this object under its given name.
It is only used internally to register and construct particular calendars.
Use the instance function instead to retrieve calendars.$.calendars.calendars.gregorian = GregorianCalendar; |
| baseCalendar | BaseCalendar | BaseCalendar | This attribute provides access to the base "class" from which other
calendar implementations inherit. It contains common code used by
all calendars. It is only used internally to implement new
calendars.JulianCalendar.prototype = new $.calendars.baseCalendar; |
| regional | object[] | See below | The base calendar processing may be localised by adding entries to this attribute,
and then referring to them with the local attribute.
Each entry is indexed by its language code and its value is an object
with the regional fields shown below.Within these values use '{n}', where n is a number starting from zero, to indicate insertion points for message-specific details. $.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}'}; |
| local | object | $.calendars.regional[''] | The regional settings that are currently in use are referenced by this attribute.
You would only change this to localise the standard error messages generated
by calendar implementations.$.calendars.local = $.calendars.regional['fr']; |
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
| Signature | Returns | Comments |
|---|---|---|
| newDate(year, month, day) | CDate object | Create a new date using this date's calendar.
You can also create dates directly
and from a calendar.
An error is thrown if the requested date is invalid.year (number, optional) is the year for the new date.
If no parameters are specified the current date is cloned.month (number, optional) is the month for the new date.day (number, optional) is the day for the new date.var date1 = date.newDate(); // Clone
var date2 = date.newDate(2010, 1, 26); |
| year(year) | this CDate or number | Set or retrieve the year for this date. If no parameter is supplied
the current year is returned. Otherwise the year for the date is
changed and the date object is returned. Use negative values for
years before the current epoch. This is equivalent to
set(year, 'y'). To change all the periods,
use the date() function.
An error is thrown if the requested date is invalid.year (number, optional) is the new year for the date.var y = date.year();
date.year(2008); |
| month(month) | this CDate or number | Set or retrieve the month for this date. If no parameter is supplied
the current month is returned. Otherwise the month for the date is
changed and the date object is returned. This is equivalent to
set(month, 'm'). To change all the periods,
use the date() function.
An error is thrown if the requested date is invalid.month (number, optional) is the new month for the date.var m = date.month();
date.month(2); |
| day(day) | this CDate or number | Set or retrieve the day for this date. If no parameter is supplied
the current day is returned. Otherwise the day for the date is
changed and the date object is returned. This is equivalent to
set(day, 'd'). To change all the periods,
use the date() function.
An error is thrown if the requested date is invalid.day (number, optional) is the new day for the date.var d = date.day();
date.day(29); |
| date(year, month, day) | this CDate | Set this date's values. To change individual periods,
use the year(), month(),
day(), or set() functions.
An error is thrown if the requested date is invalid.year (number) is the new year for this date.month (number) is the new month for this date.day (number) is the new day for this date.date.date(2004, 1, 26); |
| leapYear() | boolean | Determine whether or not this date is in a leap year. It returns
true if it is, or false if it is not.
You can also determine a leap year from the
calendar.if (date.leapYear()) ... |
| epoch() | string | Retrieve the epoch designator for this date. For the Gregorian
calendar this is 'BCE' for negative years or 'CE' for positive years.
You can also find the epoch from the
calendar.var e = date.epoch(); |
| formatYear() | string | Retrieve the formatted year for this date. Typically this is
the same as the normal year, padded to four digits.
For the Mayan calendar it is the long count year in the
format: b'ak'tun.k'atun.tun.
You can also find the formatted year from the
calendar.var fy = date.formatYear(); |
| monthOfYear() | number | Retrieve the ordinal month number for this date, i.e. the number of
the month within a numbered year as opposed to its number within the
list of months. This is only different in the Hebrew calendar
where the year numbering changes on month 7.
You can also find the month of the year from the
calendar.var moy = date.monthOfYear(); |
| weekOfYear(); | number | Retrieve the number of the week within the year in which this date
is located. By default this uses the ISO 8601 definition of a week:
weeks start on Monday, the first week of the year contains the first
Thursday of the year. This means that some dates at the start and end
of some years will appear in weeks from other years.
You can also find the week of the year from the
calendar.var woy = date.weekOfYear(); |
| daysInYear() | number | Retrieve the number of days in this date's year.
You can also find the days in a year from the
calendar.var diy = date.daysInYear(); |
| dayOfYear() | number | Retrieve this date's position within the year.
It returns 1 through the number of
days in the year.
You can also find the day of the year from the
calendar.var doy = date.dayOfYear() |
| daysInMonth() | number | Retrieve the number of days in this date's month.
You can also find the days in a month from the
calendar.var dim = date.daysInMonth(); |
| dayOfWeek() | number | Determine this date's day of the week. The returned value ranges from
zero to one less than the number of
days in the week,
with 0 being Sunday (or equivalent), 1 being Monday, etc.
You can also find the day of the week from the
calendar.var dow = date.dayOfWeek(); |
| weekDay() | boolean | Determine whether or not this date is a normal week day.
It returns true if it is (Monday through Friday in the
Gregorian calendar), or false if it is not.
You can also determine week days from the
calendar.if (date.weekDay()) ... |
| extraInfo() | object | Retrieve extra information about this date - the returned
object's attributes depend on the calendar implementation.
For example, the Mayan calendar returns the corresponding
Tzolkin and Haab dates.
You can also find the extra information about a day from the
calendar.var ei = date.extraInfo();
alert(ei.tzolkinDayName); |
| add(offset, period) | this CDate | Add a number of periods to this date. If changing by month or year
and the new month has fewer days, the day is adjusted to the end
of that new month. You can also add periods from the
calendar.offset (number) is the amount of change, which may be negative.period (string) is the unit of change: 'y' for years,
'm' for months, 'w' for weeks, 'd' for days.date.add(1, 'w');
date.add(-18, 'm');
date.add(1, 'y').add(1, 'd'); |
| set(value, period) | this CDate | Set a period for this date. An error is thrown if the
requested date is invalid. Alternately, use the
year(), month(), or
day() functions. To change all the periods,
use the date() function. You can also set periods from the
calendar.value (number) is the new period value.period (string) is the period designator:
'y' for year, 'm' for month, 'd' for day.date.set(2010, 'y');
date.set(1, 'm').set(16, 'd'); |
| compareTo(date) | number | Compare this date to another date. It returns -1 if this date is
before the other date, 0 if they are equal, or +1 if this date
is after the other date. An error is thrown if the two dates
belong to different calendars.date (CDate) is the other date to compare.if (date.compareTo(date2) == -1) ... |
| calendar() | *Calendar | Retrieve the calendar implementation backing this date.var c = date.calendar(); |
| toJD() | number | Retrieve the Julian date for this date. This is the
number of days since 1 January, 4713 BCE, Greenwich noon.
You can also convert to a Julian date from the
calendar.var jd = date.toJD(); |
| fromJD(jd) | CDate | Create a new date for a given Julian date.jd (number) is the Julian date to convert.
Typically it would end in .5, e.g. 2454857.5.
You can also convert from a Julian date from the
calendar.var date2 = date.fromJD(jd); |
| toJSDate() | Date | Convert this date into the equivalent JavaScript Date.
You can also convert to a JavaScript Date from the
calendar.var jsd = date.toJSDate(); |
| fromJSDate(jsd) | CDate | Convert a JavaScript Date into the equivalent CDate.
You can also convert from a JavaScript date from the
calendar.jsd (Date) is the JavaScript date to convert.var date2 = date.fromJSDate(jsd); |
| toString() | string | Retrieve a string representation of this date.
Usually this would be for debugging purposes only. You should use the
formatDate
function for more flexible formatting.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
| Signature | Returns | Comments |
|---|---|---|
| newDate(year, month, day) | CDate | Create a new date object within this calendar. You can also create
dates directly
or from another date.
An error is thrown if the requested date is not valid.year (CDate) is a date to clone or
(number) is the year for the new date.month (number, optional) is the month for the date.day (number, optional) is the day for the date.var d = gc.newDate(2009, 1, 26);
var d2 = gc.newDate(d);
var d = pc.newDate(1388, 1, 1); |
| today() | CDate | Create a new date object representing today within this calendar.var d = gc.today(); |
| leapYear(year) | boolean | Determine whether or not this date is in a leap year. It returns
true if it is, or false if it is not.
You can also determine a leap year from the
date itself.year (CDate) is a date to get the year from or
(number) is the year to examine.if (gc.leapYear(d)) ...
if (hc.leapYear(5768)) ... |
| epoch(year) | string | Retrieve the epoch designator for this date. For the Gregorian calendar
this is 'BCE' for negative years or 'CE' for positive years.
You can also find the epoch from the
date itself.year (CDate) is a date to get the year from or
(number) is the year to examine.var e = gc.epoch(d);
var e = pc.epoch(1388); |
| formatYear(year) | string | Retrieve the formatted year for this date. Typically this is
the same as the normal year, padded to four digits.
For the Mayan calendar it is the long count year in the
format: baktun.katun.tun.
You can also find the formatted year from the
date itself.year (CDate) is a date to get the year from or
(number) is the year to examine.var fy = gc.formatYear(d);
var fy = mc.newDate(5160); |
| monthsInYear(year) | number | Retrieve the number of months in a given year for this calendar.year (CDate) is a date to get the year from or
(number) is the year to examine.var m = gc.monthsInYear(d);
var m = hc.monthsInYear(5768); // = 13 |
| monthOfYear(year, month) | number | Retrieve the ordinal month number for a given month, i.e. the number of
the month within a numbered year as opposed to its number within the
list of months. This is only different in the Hebrew calendar
where the year numbering changes on month 7.
You can also find the month of the year from the
date itself.
The inverse function is fromMonthOfYear.year (CDate) is a date to get the month from or
(number) is the year to exmaine.month (number, optional) is the month to examine.var moy = gc.monthOfYear(d);
var moy = hc.monthOfYear(5768, 7); // = 1 |
| fromMonthOfYear(year, ord) | number | Retrieve the month for a given ordinal month number, i.e. the number of
the month within the list of months as opposed to its number within
a numbered year. This is only different in the Hebrew calendar
where the year numbering changes on month 7. The inverse function is
monthOfYear.year(number) is the year to exmaine.ord (number) is the ordinal month number.var m = gc.fromMonthOfYear(y, o); |
| weekOfYear(year, month, day) | number | Retrieve the number of the week within the year in which a date
is located. By default this uses the ISO 8601 definition of a week:
weeks start on Monday, the first week of the year contains the first
Thursday of the year. This means that some dates at the start and end
of some years will appear in weeks from other years.
An error is thrown if the date is not valid for the calendar.
You can also find the week of the year from the
date itself.year (CDate) is the date to examine or
(number) is the year to examine.month (number, optional) is the month to examine.day (number, optional) is the day to examine.var woy = gc.weekOfYear(d);
var woy = pc.weekOfYear(1388, 1, 1); |
| daysInYear(year) | number | Retrieve the number of days in a given year.
You can also find the day in a year from the
date itself.year (CDate) is a date to get the year from or
(number) is the year to examine.var diy = gc.daysInYear(d);
var diy = hc.daysInYear(5768); |
| dayOfYear(year, month, day) | number | Retrieve the number of the given day within its year.
An error is thrown if the date is not valid for the calendar.
You can also find the day of the year from the
date itself.year (CDate) is a date to examine or
(number) is the year to examine.month (number, optional) is the month to examine.day (number, optional) is the day to examine.var doy = gc.dayOfYear(d);
var doy = pc.dayOfYear(1388, 1, 1); |
| daysInMonth(year, month) | number | Retrieve the number of days in a given month.
An error is thrown if the year or month is invalid.
You can also find the days in a month from the
date itself.year (CDate) is a date to get the month and
year from or (number) is the year to examine.month (number, optional) is the month to examine.var dim = gc.daysInMonth(d);
var dim = pc.daysInMonth(1388, 12); |
| daysInWeek() | number | Retrieve the number of days in a week.var diw = gc.daysInWeek(); |
| dayOfWeek(year, month, day) | number | Retrieve the number of the given day within its week.
An error is thrown if the date is not valid for the calendar.
You can also find the day of the week from the
date itself.year (CDate) is a date to examine or
(number) is the year to examine.month (number, optional) is the month to examine.day (number, optional) is the day to examine.var dow = gc.dayOfWeek(d);
var dow = pc.dayOfWeek(1388, 1, 1); |
| weekDay(year, month, day) | boolean | Determine whether or not this date is a normal week day.
It returns true if it is (Monday through Friday in the
Gregorian calendar), or false if it is not.
You can also determine a week day from the
date itself.year (CDate) is a date to examine or
(number) is the year to examine.month (number, optional) is the month to examine.day (number, optional) is the day to examine.if (gc.weekDay(d)) ...
if (pc.weekDay(1388, 1, 1)) ... |
| extraInfo(year, month, day) | object | Retrieve extra information about this date - the returned
object's attributes depend on the calendar implementation.
For example, the Mayan calendar returns the corresponding
Tzolkin and Haab dates.
An error is thrown if the date is not valid for the calendar.
You can also find extra information from the
date itself.year (CDate) is a date to examine or
(number) is the year to examine.month (number, optional) is the month to examine.day (number, optional) is the day to examine.var ei = hc.extraInfo(d);
var ei = mc.extraInfo(5160, 1, 1);
alert(ei.tzolkinDayName); |
| add(date, offset, period) | CDate | Add a number of periods to a date and return the modified date.
If changing by month or year and the new month has fewer days,
the day is adjusted to the end of that new month.
You can also add periods to the
date itself.date (CDate)the day to modify.offset (number) is the amount of change; it may be negative.period (string) is the unit of change: 'y' for years,
'm' for months, 'w' for weeks, 'd' for days.gc.add(d, 1, 'w');
gc.add(d, 18, 'm'); |
| set(date, value, period) | CDate | Set a period for a date.
An error is thrown if the date is not valid for the calendar.
You can also set periods for the
date itself.date (CDate)the day to modify.value (number) is the new period value.period (string) is the period designator:
'y' for year, 'm' for month, 'd' for day.gc.set(d, 2010, 'y');
pc.set(d, 1, 'm'); |
| isValid(year, month, day) | boolean | Determine whether or not a given date is valid within this calendar.
It returns true if valid, or false if not.year (number) is the year to examine.month (number) is the month to examine.day (number) is the day to examine.if (gc.isValid(2009, 1, 26)) ... // true
if (gc.isValid(2009, 2, 29)) ... // false |
| toJD(year, month, day) | number | Convert a date into its Julian date equivalent. This is the
number of days since 1 January, 4713 BCE, Greenwich noon.
An error is thrown if the date is not valid for the calendar.
You can also convert to a Julian date from the
date itself.year (CDate) is a date to convert or
(number) is the year to convert.month (number, optional) is the month to convert.day (number, optional) is the day to convert.var jd = gc.toJD(d);
var jd = pc.toJD(1388, 1, 1); |
| fromJD(jd) | CDate | Create a new date for a given Julian date.
You can also convert from a Julian date from another
date.jd (number) is the Julian date to convert.
Typically it would end in .5, e.g. 2454857.5.var d = gc.fromJD(jd); |
| toJSDate(year, month, day) | Date | Convert this date into the equivalent JavaScript Date.
An error is thrown if the date is not valid for the calendar.
You can also convert to a JavaScript Date from the
date itself.year (CDate) is a date to convert or
(number) is the year to convert.month (number, optional) is the month to convert.day (number, optional) is the day to convert.var jsd = gc.toJSDate(d);
var jsd = pc.toJSDate(1388, 1, 1); |
| fromJSDate(jsd) | CDate | Convert a JavaScript Date into the equivalent CDate.
You can also convert from a JavaScript Date from another
date.jsd (Date) is the JavaScript date to convert.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.
| Name | Type | Comments |
|---|---|---|
| name | string | The unchanging name of this calendar implementation. |
| jdEpoch | number | The Julian Date of the start of the epoch for this calendar, e.g. the date for 1 January 0001 CE in the Gregorian calendar. |
| hasYearZero | boolean | True if this calendar has a year zero or
false if not. |
| minMonth | number | The minimum month number, e.g. 1 in most calendars but 0 in the Mayan calendar. |
| firstMonth | number | The number of the first month within a year, e.g. the same as minMonth
in most calendars, but 7 in the Hebrew calendar. |
| minDay | number | The minimum day number, e.g. 1 in most calendars but 0 in the Mayan calendar. |
| regional | object[] | The localised settings for this calendar. Entries are indexed by their language code and consist of an object with the fields shown below. |
| Name | Type | Comments |
|---|---|---|
| name | string | The name of this calendar implementation. |
| epochs | string[2] | The epoch indicators, e.g. 'BCE' and 'CE' for the Gregorian calendar. |
| monthNames | string[] | The full names of the months. |
| monthNamesShort | string[] | The abbreviated names of the months. |
| dayNames | string[] | The full names of the days of the week. |
| dayNamesShort | string[] | The abbreviated names of the days of the week. |
| dayNamesMin | string[] | The minimal names of the days of the week. |
| dateFormat | string | The default date format. See the formatDate function for a description of this field. |
| firstDay | number | The first day of the week, 0 = Sunday, 1 = Monday, ... |
| isRTL | boolean | True if this language runs right-to-left or
false if it does not. |
Several world calendars are implemented within this plugin. Details about their implementation are shown below.
Coptic | Ethiopian | Gregorian | Hebrew | Islamic | Julian | Mayan | Persian | Taiwan | Thai
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 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 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 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 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 the Islamic calendar using the '16 civil' version. It is used in many Muslim countries. Points to note are:
This is the civil Hebrew calendar. It is used by Jews and followers of Judaism. Points to note are:
extraInfo
returns an explanation of the year type in yearType.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 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 the Mayan Long Count calendar used by the Maya civilization of pre-Columbian Mesoamerica. Points to note are:
extraInfo
returns the Tzolkin date details in tzolkinDayName,
tzolkinDay, and tzolkinTrecena,
and the Haab date details in haabMonthName,
haabMonth, and haabDay.forYear function to convert from the formatted year
back to a sequential number.The plus module adds extra functionality to
CDate.
| Signature | Returns | Comments |
|---|---|---|
| formatDate(format) | string | Format a date into a string representation.format (string, optional) is the format to apply (see the
calendar version for a full description).
If not specified, it uses the default format for the calendar.var f = d.formatDate();
var f = d.formatDate('yyyy-mm-dd'); |
The plus module adds extra functionality to
calendars.
determineDate | formatDate | parseDate
| Signature | Returns | Comments |
|---|---|---|
| formatDate(format, date, settings) | string | Format a date into a string representation.
An error is thrown if the date belongs to a different calendar.format (string, optional) is the format to apply, consisting of
any combination of the specifications below or one of the
predefined formats. If not specified,
it uses the default format for the calendar.
date (CDate)
is the date to format.settings (object, optional) is any overrides for the
formatting, being an object with the following attributes - all are optional
with the current calendar settings being used if they are not present:dayNames (string[])
is the full names of the daysdayNamesShort (string[])
is the abbreviated names of the daysmonthNames (string[])
is the full names of the monthsmonthNamesShort (string[])
is the abbreviated names of the monthscalculateWeek (function)
is a function to determine the week of the year - it receives a CDate
as a parameter and returns a number being the corresponding weekvar 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', ...]}); |
| parseDate(format, value, settings) | CDate | Convert a string representation into an actual date.format (string) is the format to apply. See the
possibilities in the formatDate
function, with the following addition:
value (string) is the string to extract the date from.settings (object, optional) is any overrides for the
parsing, being an object with the following attributes - all are optional
with the current calendar settings being used if they are not present:dayNames (string[])
is the full names of the daysdayNamesShort (string[])
is the abbreviated names of the daysmonthNames (string[])
is the full names of the monthsmonthNamesShort (string[])
is the abbreviated names of the monthsshortYearCutoff (number or string)
is the cutoff point for the current or previous century when using the
shortened year format; if this is a string it is added to the current
year value, e.g. '+10'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', ...]}); |
| determineDate(dateSpec, defaultDate, currentDate, dateFormat, settings) | CDate | Convert multiple representations of a date into an actual date.dateSpec (CDate) is the date to use or
(number) is the offset in days from today or
(string) is the date in the current format or
(string) is one or more amounts and periods to offset from today.
For the last use 'y' for years, 'm' for months, 'w' for weeks, or 'd' for days,
e.g. '+1y +1d'. Prefix the value with 'c' to use the currentDate
as the starting point instead of today.defaultDate (CDate) is the date to use if no other is
specified. It may be null.currentDate (CDate, optional) is the current date to base
offsets from. Today is used if this is not specified.dateFormat (string, optional) is the date format to
use to check the dateSpec. If not specified,
the current format for the calendar is used.settings (object, optional) is any overrides for the formatting.
See the formatDate function for more details.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:
| Name | Value | Comments |
|---|---|---|
| ATOM | yyyy-mm-dd | RFC 3339/ISO 8601 |
| COOKIE | D, dd M yyyy | |
| FULL | DD, MM d, yyyy | |
| ISO_8601 | yyyy-mm-dd | |
| JULIAN | J | |
| RFC_822 | D, d M yy | |
| RFC_850 | DD, dd-M-yy | |
| RFC_1036 | D, d M yy | |
| RFC_1123 | D, d M yyyy | |
| RFC_2822 | D, d M yyyy | |
| RSS | D, d M yy | RFC 822 |
| TICKS | ! | |
| TIMESTAMP | @ | |
| W3C | yyyy-mm-dd | ISO 8601 |
Several error messages used during parsing and formatting are added to the global regional settings.
Contact Keith Wood at kbwood{at}iinet.com.au with comments or suggestions.