Calendar Modules

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.

ModulePurposeDependencies
jquery.calendars.js Base calendar support, including custom CDate object and Gregorian calendar. See separate documentation. -
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.ummalqura.js Umm al-Qura calendar support - also known as the Saudi calendar. Written by Amro Osama.
Since 1.2.1.
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.nepali.js Nepali calendar support - also known as Vikram Samvat. Written by Artur Neumann.
Since 1.2.1.
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. 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. -
jquery.calendars.validation.js Validation plugin extensions for datepicker fields. Base, Plus, Picker
Datepicker Settings

Customise each targetted field with the settings below (all are optional):

$(selector).calendarsPicker({dateFormat: 'yyyy-mm-dd'});

alignment | altField | altFormat | autoSize | calculateWeek | calendar | changeMonth | commands | commandsAsDateFormat | constrainInput | dateFormat | defaultDate | firstDay | fixedWeeks | maxDate | minDate | monthsOffset | monthsToJump | monthsToShow | monthsToStep | multiSelect | multiSeparator | onChangeMonthYear | onClose | onDate | onSelect | onShow | pickerClass | popupContainer | rangeSelect | rangeSeparator | selectDefaultDate | selectOtherMonths | showAnim | showOnFocus | showOptions | showOtherMonths | showSpeed | showTrigger | useMouseWheel | yearRange

NameTypeDefaultComments
calendar *Calendar $.calendars.instance The calendar implementation that backs this datepicker. Current implementations are Gregorian (default), Taiwan, Thai, Julian, Persian, Islamic, Umm al-Qura, Hebrew, Ethiopian, Coptic, Nepali, and Mayan.

$(selector).calendarsPicker({calendar:
	$.calendars.instance('persian', 'fa')});
pickerClassstring'' Any extra CSS class(es) to add to this datepicker instance. By specifying a unique class you can individually target datepicker instances with special styling.

$(selector).calendarsPicker({pickerClass: 'my-picker'});
showOnFocusbooleantrue When true a popup datepicker appears for an input field when it gains focus. When false you should specify a showTrigger instead.
showTriggerstring or element or jQuerynull The element(s) that will trigger a popup datepicker to appear when they are clicked. You can provide either the element itself, a jQuery collection containing the element, a string selector for the desired element, or a string version of the element. The trigger is cloned and placed after the input field (taking right-to-left languages into account).

$(selector).calendarsPicker({showTrigger:
	'<img src="img/calendar.gif" alt="Popup" class="trigger">'});
$(selector).calendarsPicker({showTrigger: '#myicon'});
showAnimstring'show' The name of the animation to use when a popup datepicker appears and disappears. The value can be one of the standard animations - 'show', 'fadeIn', or 'slideDown' - or any of the jQuery UI effects (provided you have included the appropriate plugin). Set this to '' for no animation.

$(selector).calendarsPicker({showAnim: 'fadeIn'});
$(selector).calendarsPicker({showAnim: 'clip'});
$(selector).calendarsPicker({showAnim: ''}); // Immediate
showOptionsobject{} For jQuery UI animations you can specify any additional options with this setting. For example, the clip animation can be set to run horizontally instead of vertically.

$(selector).calendarsPicker({
	showAnim: 'clip', showOptions: {direction: 'horizontal'}});
showSpeedstring or number'normal' The speed at which the animation runs. Use one of the standard speeds - 'slow', 'normal', or 'fast' - or specify the duration in milliseconds.

$(selector).calendarsPicker({showSpeed: 'fast'});
$(selector).calendarsPicker({showSpeed: 1500});
popupContainer string or element or jQuerynull The container for the popup datepicker, allowing you to control where in the DOM the datepicker is appended. You can provide either the element itself, a jQuery collection containing the element, or a string selector for the desired element. It defaults to the document body.

$(selector).calendarsPicker({popupContainer: '#mydiv'});
alignmentstring'bottom' Control the alignment of a popup datepicker with respect to its input field. Use one of the following values: 'bottom' for below or 'top' for above, both of which are left- or right- aligned depending on the localisation preference, or 'topLeft', 'topRight', 'bottomLeft', or 'bottomLeft'. The first two options will reposition the datepicker if it does not fit in the requested space.
fixedWeeksbooleanfalse Set to true to always have six weeks shown, or false to only show as many weeks as are needed. This setting only applies to a datepicker for a single month as all multi-month datepickers are always fixed.
firstDaynumbernull The number of the first day of the week shown in the datepicker, with 0 being Sunday, 1 being Monday, etc. If set to null the first day from the underlying calendar is used.
calculateWeekfunctionnull A function to calculate the week of the year for a given date. The date (CDate) is passed as a parameter and the function returns a number indicating the corresponding week of the year. If set to null the week calculation from the underlying calendar is used. You should use the weekOfYearRenderer to actually display the value.

$(selector).calendarsPicker({calculateWeek: myWeek,
	renderer: $.calendars.picker.weekOfYearRenderer});
	
function myWeek(date) {
	return Math.floor((date.dayOfYear() - 1) / 7) + 1;
}
monthsToShownumber or number[2]1 The number of months to show in the datepicker. It may be expressed as a single number of columns, or as an array of rows and columns.

$(selector).calendarsPicker({monthsToShow: 3});
$(selector).calendarsPicker({monthsToShow: [2, 3]});
monthsOffsetnumber0 When showing multiple months, this setting indicates at which position the current month is shown, starting from zero. The example below shows three months with the current one in the middle.

$(selector).calendarsPicker({
	monthsToShow: 3, monthsOffset: 1});
monthsToStepnumber1 The number of months to move when the previous or next month commands are invoked.
monthsToJumpnumber12 The number of months to move when the previous or next year commands are invoked.
useMouseWheelbooleantrue If the MouseWheel plugin is available and this setting is true then you can use the mouse wheel to step through the months or years (with the Ctrl key). If this setting is false then the mouse wheel has no effect within the datepicker, even if the plugin is available.

Since 1.1.2.
changeMonthbooleantrue Set to true to allow the month and year to be changed via a drop-down selection on the first month shown in the datepicker. Set to false to only allow changes via the various previous and next commands.
yearRangestring'c-10:c+10' Specify the range of years shown in the year drop-down. The setting contains the start and end of the range separated by a colon (:). Each limit may be an absolute year ('1980'), an offset from today ('-10' or '+10'), or an offset from the currently selected date ('c-5' or 'c+5'). Place the maximum value first to have the list appear in descending order. Set to 'any' to allow direct input of the year without selection from a drop-down list. The default is to show 10 years before and after the currently selected date.

Note that this setting does not restrict the dates that may be selected. You should use the minDate and maxDate settings to impose limits on the dates that may be selected.

$(selector).calendarsPicker({yearRange: '1980:2000'});
$(selector).calendarsPicker({yearRange: '1960:-18'});
$(selector).calendarsPicker({yearRange: 'c+10:c-10'}); // Descending
$(selector).calendarsPicker({yearRange: 'any'});

Since 1.1.2 - descending ranges.
showOtherMonthsbooleanfalse Set to true to show the days in other months that appear in the partial weeks before or after the current month.
selectOtherMonthsbooleanfalse Set to true to allow the days in other months that appear in the partial weeks before or after the current month to be selected. This setting only applies if showOtherMonths is true.

$(selector).calendarsPicker({
	showOtherMonths: true, selectOtherMonths: true});
defaultDate CDate or number or stringnull Specify the date to show if no other date has been selected. This may be specified as an actual date (CDate), as a date string in the current dateFormat, as a number of days relative to today, or as a string of offsets and periods relative to today. For the last use 'y' for years, 'm' for months, 'w' for weeks, or 'd' for days. Multiple offsets may be combined in the one string. Set to null for a default date of today.

$(selector).calendarsPicker({
	defaultDate: calendar.newDate(2009, 1, 26)});
$(selector).calendarsPicker({defaultDate: '01/26/2009'});
$(selector).calendarsPicker({defaultDate: +7});
$(selector).calendarsPicker({defaultDate: '+1m -1d'});
selectDefaultDatebooleanfalse Set to true to automatically select the defaultDate when no other date has been selected.

$(selector).calendarsPicker({
	defaultDate: '01/26/2009', selectDefaultDate: true});
minDate CDate or number or stringnull Specify the minimum date allowed to be selected. This may be specified as an actual date (CDate), as a date string in the current dateFormat, as a number of days relative to today, or as a string of offsets and periods relative to today. For the last use 'y' for years, 'm' for months, 'w' for weeks, or 'd' for days. Multiple offsets may be combined in the one string. Set to null for no minimum.

$(selector).calendarsPicker({
	minDate: calendar.newDate(2008, 12, 25)});
$(selector).calendarsPicker({minDate: '12/25/2008'});
$(selector).calendarsPicker({minDate: -10});
$(selector).calendarsPicker({minDate: '-1m -15d'});
maxDate CDate or number or stringnull Specify the maximum date allowed to be selected. This may be specified as an actual date (CDate), as a date string in the current dateFormat, as a number of days relative to today, or as a string of offsets and periods relative to today. For the last use 'y' for years, 'm' for months, 'w' for weeks, or 'd' for days. Multiple offsets may be combined in the one string. Set to null for no maximum.

$(selector).calendarsPicker({
	maxDate: calendar.newDate(2009, 12, 25)});
$(selector).calendarsPicker({maxDate: '12/25/2009'});
$(selector).calendarsPicker({maxDate: +10});
$(selector).calendarsPicker({maxDate: '+1m +15d'});
dateFormatstringnull Specify the format applied to the selected dates. This may be any combination of the values below. To use any of these characters without substitution you must surround them in single quotes ('). If set to null the default date format specified by the calendar is used instead.

  • d - day of the month (no leading zero)
  • dd - day of the month (two digit)
  • D - day name short
  • DD - day name long
  • o - day of the year (no leading zeros)
  • oo - day of the year (three digits)
  • w - week of year (no leading zero)
  • ww - week of year (two digit)
  • m - month of the year (no leading zero)
  • mm - month of the year (two digit)
  • M - month name short
  • MM - month name long
  • yy - year (two digit)
  • yyyy - year (four digit)
  • YYYY - formatted year (depends on calendar)
  • J - Julian date
  • @ - Unix timestamp (ms since 01/01/1970)
  • ! - Windows ticks (100ns since 01/01/0001)
  • '...' - literal text
  • '' - single quote

Or you can use one of the predefined formats from the calendar:

  • ATOM - 'yyyy-mm-dd'
  • 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'
  • TICKS - '!'
  • TIMESTAMP - '@'
  • W3C - 'yyyy-mm-dd'

$(selector).calendarsPicker({dateFormat: 'yyyy-mm-dd'});
$(selector).calendarsPicker({dateFormat: 'dd-M-yyyy'});
$(selector).calendarsPicker({dateFormat: calendar.FULL});
autoSizebooleanfalse Set to true to resize the input field based on the maximum length of a date in the current dateFormat. Set to false to not change the field length.
rangeSelectbooleanfalse Set to true to allow the selection of a date range in the datepicker. The first selected date is the start of the range and the second selected date is the end of the range. A popup datepicker closes automatically on selection of the range end. Set to false to select a single date.
rangeSeparatorstring' - ' Specify the separator shown between the two dates in a date range.
multiSelectnumber0 Specify the maximum number of individual separate dates that may be selected in the datepicker. Dates may be de-selected by clicked on them a second time. A popup datepicker closes automatically on selection of the maximum number allowed. Set to 0 to select a single date.
multiSeparatorstring',' Specify the separator shown between the dates selected in a multiple date datepicker.
onDatefunctionnull Specify a callback function to provide additonal details about individual dates shown in the datepicker. The function is called for each date displayed and receives the date as a parameter (CDate), while this refers to the associated control. It returns an object with the following attributes (all optional):

selectable (boolean) true if the date is selectable, false if not;

dateClass (string) any CSS class(es) to apply to this date;

title (string) a tooltip for this date;

content (string) content for this date to replace the basic day number.

$(selector).calendarsPicker({
	onDate: function(date) {
	    return {content: date.day() + '<br><sub>' +
			date.dayOfYear() + '</sub>',
			dateClass: 'showDoY'};
	}
});
onShowfunctionnull Specify a callback function to provide additonal functionality to a datepicker. The function is called just before the datepicker is shown and receives the completed datepicker division as a jQuery object, the underlying calendar implementation, and the current instance settings as parameters, while this refers to the associated control. It should update the datepicker division as necessary. See the various examples in the picker.ext module. If you need multiple onShow callbacks, use the multipleEvents function and pass the relevant handlers to it.

$(selector).calendarsPicker({
	onShow: function(picker, calendar, inst) {
	    picker.find('td:even').addClass('alternate-dates');
	}
});
onChangeMonthYearfunctionnull Specify a callback function to be notified of changes to the month and year shown in a datepicker. The function is called when the month/year changes and receives the year and month as parameters, while this refers to the associated control. If you need multiple onChangeMonthYear callbacks, use the multipleEvents function and pass the relevant handlers to it.

$(selector).calendarsPicker({
	onChangeMonthYear: function(year, month) {
	    $('#monthYear').text(month + '/' + year);
	}
});
onSelectfunctionnull Specify a callback function to be notified of date selection in a datepicker. The function is called when each date is selected and receives the currently selected dates (CDate[]) as the parameter, while this refers to the associated control. The array is empty if no dates have been selected. Note that when the start of a range is selected the dates array contains two entries, with both being that starting date. If you need multiple onSelect callbacks, use the multipleEvents function and pass the relevant handlers to it.

$(selector).calendarsPicker({
	onSelect: function(dates) {
	    $('#count').text('Selected ' + dates.length + ' date(s)');
		var minDate = dates[0];
		for (var i = 1; i < dates.length; i++) {
			if (dates[i].compareTo(minDate) == -1) {
				minDate = dates[i];
			}
		}
		$('#minDate').text(minDate.formatDate());
	}
});
onClosefunctionnull Specify a callback function to be notified of a popup datepicker closing. The function is called when the datepicker is closed (by any means) and receives the currently selected dates (CDate[]) as the parameter, while this refers to the associated control. The array is empty if no dates have been selected. Note that range selections always have two entries, with both being the starting date if no end date has been selected. If you need multiple onClose callbacks, use the multipleEvents function and pass the relevant handlers to it.

$(selector).calendarsPicker({
	onClose: function(dates) {
		var selected = '';
		for (var i = 0; i < dates.length; i++) {
			selected += ',' + dates[i].formatDate();
		}
	    alert('Selected dates are: ' + selected.substring(1));
	}
});
altFieldstring or element or jQuerynull Specify another field to be updated in sync with the datepicker selections. This and the following setting allow you to automatically show selected dates in one format for the user, while maintaining a second field with a more useful format for further processing. The alternate field may be specified as either the element itself, a jQuery collection containing the element, or a string selector for the desired element.

$(selector).calendarsPicker({dateFormat: 'DD, MM d, yyyy',
	altField: '#isoDate', altFormat: 'yyyy-mm-dd'});
altFormatstringnull Use in conjunction with the altField setting to automatically maintain two different views of the selected date(s). See the dateFormat setting for the list of possible values.
constrainInputbooleantrue Set to true to only allow the entry of characters specified by the dateFormat, or false to allow any characters.
commandsAsDateFormatbooleanfalse Set to true to apply the formatDate function to all command display text. This allows you to label commands with the dates to which they refer, for example the previous and next links could show the month to which they move. Remember to quote (') any command text you do not want substituted.

$(selector).calendarsPicker({commandsAsDateFormat: true,
	prevText: '< M', currentText: 'M y', nextText: 'M >'});
commandsobject$.calendars.picker.commands See the Commands tab for more details.
Datepicker Commands

The datepicker contains a series of commands that operate upon it, allowing these to be customised or new commands added. Each command consists of an object with the attributes shown below, and is added to the commands setting. The standard commands are listed below.

NameTypeComments
textstring The name of the localisation setting that provides the text value for this command.
statusstring The name of the localisation setting that provides the tooltip (status) value for this command.
keystrokeobject The keystroke that triggers this command. The object's attributes are:

keyCode (number) the numeric code for the keystroke;

ctrlKey (boolean, optional) true if the Ctrl key must be used in conjunction with the above keyCode;

altKey (boolean, optional) true if the Alt key must be used in conjunction with the above keyCode;

shiftKey (boolean, optional) true if the Shift key must be used in conjunction with the above keyCode.
enabledfunction The function that indicates whether the command can be invoked at present. It takes the current instance settings as a parameter, while this is the associated target control. It returns true if the command may be executed or false if it may not.
datefunction The function that provides a target date for this command. For example, the target date for the previous command is the first day of the previous month. It takes the current instance settings as a parameter, while this is the associated target control. It returns a CDate if an appropriate date can be determined or null if not.
actionfunction The function that implements the action for this command. It takes the current instance settings as a parameter, while this is the associated target control.

Standard Commands

The standard commands defined by the datepicker are shown below and are available as $.calendars.picker.commands. These may be positioned in the datepicker by including the '{link:name}' or '{button:name}' substitution points in the renderer values, where name is the command name below.

NameTextStatusKeystroke EnabledDateAction
prev prevText prevStatusPage Up If not at the minDate First day of previous month Move to the previous month (depending on the monthsToStep setting)
prevJump prevJumpText prevJumpStatusCtrl+Page Up If not at the minDate First day of 12 months ago Move to 12 months ago (depending on the monthsToJump setting)
next nextText nextStatusPage Down If not at the maxDate First day of next month Move to the next month (depending on the monthsToStep setting)
nextJump nextJumpText nextJumpStatusCtrl+Page Down If not at the maxDate First day of 12 months ahead Move to 12 months ahead (depending on the monthsToJump setting)
current currentText currentStatusCtrl+Home If not outside minDate to maxDate First selected date or today Move to the month of the first selected date, or today if no date has been selected
today todayText todayStatusCtrl+Home If not outside minDate to maxDate TodayMove to today's month
clear clearText clearStatusCtrl+End Always -Clear any selected dates and close a popup datepicker
close closeText closeStatusEsc Always -Close a popup datepicker
prevWeek prevWeekText prevWeekStatusCtrl+Up If not at the minDate One week agoMove to the previous week
prevDay prevDayText prevDayStatusCtrl+Left If not at the minDate One day agoMove to the previous day
nextDay nextDayText nextDayStatusCtrl+Right If not at the maxDate One day aheadMove to the next day
nextWeek nextWeekText nextWeekStatusCtrl+Down If not at the maxDate One week aheadMove to the next week
Datepicker Localisation

These settings comprise the regional settings that may be localised by a language package. They can be overridden for individual instances:

$(selector).calendarsPicker({prevText: '<'});

clearStatus | clearText | closeStatus | closeText | currentStatus | currentText | dayStatus | defaultStatus | isRTL | monthStatus | nextJumpStatus | nextJumpText | nextStatus | nextText | prevJumpStatus | prevJumpText | prevStatus | prevText | renderer | todayStatus | todayText | weekStatus | weekText | yearStatus

NameTypeDefaultComments
rendererobject $.calendars.picker. defaultRenderer The renderer used to generate the datepicker. You can use one of the predefined renderers, define your own, or extend an existing one with minor changes. See the Renderers tab for more details.

$(selector).calendarsPicker({
	renderer: $.calendars.picker.weekOfYearRenderer});
$(selector).calendarsPicker({
	renderer: $.extend({}, $.calendars.picker.defaultRenderer,
		{picker: $.calendars.picker.defaultRenderer.picker.
			replace(/\{link:clear\}/, '{button:clear}').
			replace(/\{link:close\}/, '{button:close}')})});
prevTextstring'<Prev' The display text for the prev command. Use the commandsAsDateFormat setting to format the text to show date information.

$(selector).calendarsPicker({
	prevText: '< M', commandsAsDateFormat: true});
prevStatusstring'Show the previous month' The tooltip text for the prev command.
prevJumpTextstring'<<' The display text for the prevJump command. Use the commandsAsDateFormat setting to format the text to show date information.
prevJumpStatusstring'Show the previous year' The tooltip text for the prevJump command.
nextTextstring'Next>' The display text for the next command. Use the commandsAsDateFormat setting to format the text to show date information.

$(selector).calendarsPicker({
	nextText: 'M >', commandsAsDateFormat: true});
nextStatusstring'Show the next month' The tooltip text for the next command.
nextJumpTextstring'>>' The display text for the nextJump command. Use the commandsAsDateFormat setting to format the text to show date information.
nextJumpStatusstring'Show the next year' The tooltip text for the nextJump command.
currentTextstring'Current' The display text for the current command. Use the commandsAsDateFormat setting to format the text to show date information.
currentStatusstring'Show the current month' The tooltip text for the current command.
todayTextstring'Today' The display text for the today command. Use the commandsAsDateFormat setting to format the text to show date information.
todayStatusstring'Show today\'s month' The tooltip text for the today command.
clearTextstring'Clear' The display text for the clear command.
clearStatusstring'Clear all the dates' The tooltip text for the clear command.
closeTextstring'Close' The display text for the close command.
closeStatusstring'Close the datepicker' The tooltip text for the close command.
yearStatusstring'Change the year' The tooltip text for the year drop-down.
monthStatusstring'Change the month' The tooltip text for the month drop-down.
weekTextstring'Wk' The display text for the week of the year column header.
weekStatusstring'Week of the year' The tooltip text for the week of the year column header.
dayStatusstring'Select DD, M d, yyyy' The tooltip text for selectable days. The formatDate function is applied to the value before use.
defaultStatusstring'Select a date' The tooltip text for areas of the datepicker not covered by one of the other statuses above.
isRTLbooleanfalse Set to true to indicate that this language runs right-to-left.
Datepicker Renderers

Renderers allow you to use a templating mechanism to construct the datepicker for display. They are assigned to a datepicker instance as the renderer setting, one of the localisation settings.

You control the structure of the datepicker, the placement of controls within it, and the CSS styling that is applied to it. Substitution points of the form '{xxx}' indicate where standard content should be inserted.

There is a default renderer defined in the picker module and several alternative renderers in the picker.ext module. These are all described below.

If you define your own custom render it must contain all of the attributes described below. Alternatively you can tweak an existing renderer:

$(selector).calendarsPicker({renderer: $.extend(
	{}, $.calendars.picker.defaultRenderer,
	{picker: $.calendars.picker.defaultRenderer.picker.
		replace(/\{link:today\}/, '{link:current}')})});

commandButtonClass | commandClass | commandLinkClass | day | dayHeader | daySelector | defaultClass | disabledClass | highlightedClass | month | monthSelector | monthRow | multiClass | otherMonthClass | picker | rtlClass | selectedClass | todayClass | week | weekHeader | weekendClass

NameTypeComments
The following substitution points may be used anywhere within the renderer structure:

'{l10n:name}' to insert the localised value for name;

'{link:name}' to insert a link for command name;

'{button:name}' to insert a button for command name;

'{popup:start}...{popup:end}' to delimit sections that only appear in a popup datepicker;

'{inline:start}...{inline:end}' to delimit sections that only appear in an inline datepicker.
picker string The overall structure of the datepicker. Use:

'{months}' to insert the generated content for all of the shown months.
monthRow string The structure of a single row of months in the datepicker. Use:

'{months}' to insert the generated content for all of the months in that row.
month string The structure of a single month in the datepicker. Use:

'{monthHeader:dateFormat}' to insert the header for that month using the specified dateFormat, which is optional and defaults to 'MM yyyy';

'{weekHeader}' to insert the list of days in a week;

'{weeks}' to insert the generated content for all of the weeks in the month.
weekHeader string The structure of a single list of days in a week. Use:

'{days}' to insert the generated content for all of the days in the week.
dayHeader string The structure of a single day header. Use:

'{day}' to insert the generated content for the name of the day.
week string The structure of a single week in a month. Use:

'{days}' to insert the generated content for all of the days in that week;

'{weekOfYear}' to insert the generated content for the week of the year number.
day string The structure of a single day in a month. Use:

'{day}' to insert the generated content for the number of the day. Selectable days are enclosed in a link (a) while non-selectable days are wrapped in a span.
monthSelector string The jQuery selector, relative to a wrapper around picker, for a single month.
daySelector string The jQuery selector, relative to a wrapper around picker, for a single day.
rtlClass string Any CSS class(es) to apply to a datepicker using a right-to-left language.
multiClass string Any CSS class(es) to apply to a datepicker showing more than one month.
defaultClass string Any CSS class(es) to apply to selectable days.
selectedClass string Any CSS class(es) to apply to selected days.
highlightedClass string Any CSS class(es) to apply to the cursor day.
todayClass string Any CSS class(es) to apply to today.
otherMonthClass string Any CSS class(es) to apply to days from other months.
weekendClass string Any CSS class(es) to apply to days on weekends.
commandClass string Any CSS class(es) to apply to command links or buttons. It is also used as a prefix (followed by '-') for an additional class based on the command name.
commandButtonClass string Any CSS class(es) to apply to command buttons only.
commandLinkClass string Any CSS class(es) to apply to command links only.
disabledClass string Any CSS class(es) to apply to disabled command links or buttons.

Standard Renderers

The standard renderers are listed below. Each is accessible within the $.calendars.picker object via the given name.

NameModuleComments
defaultRendererpicker The standard renderer. Match it with the standard datepicker CSS.
weekOfYearRendererpicker.ext The standard renderer enhanced to include a column for week of the year. Match it with the standard datepicker CSS.
themeRollerRendererpicker.ext A renderer using a similar structure to the default one, but with the standard ThemeRoller classes for styling. Match it with one of the ThemeRoller CSS themes.
themeRollerWeekOfYearRendererpicker.ext The ThemeRoller renderer enhanced to include a column for week of the year. Match it with one of the ThemeRoller CSS themes.
Datepicker Globals
NameTypeDefaultComments
commandsobject[] See Commands tab The set of commands for the datepicker and the default value for the commands setting. Entries are indexed by the command name. Each entry is an object with the properties shown on the Commands tab.

You could, for example, change the keystrokes assigned to certain commands:

var altCommands = $.extend(true, {}, $.calendars.picker.commands);
altCommands.prevJump.keystroke = {keyCode: 33, altKey: true}; // Alt+PageUp
altCommands.nextJump.keystroke = {keyCode: 34, altKey: true}; // Alt+PageDown

$('#keystrokePicker').calendarsPicker({commands: altCommands,
	showTrigger: '<img src="img/calendar.gif" alt="Popup" class="trigger">'});
regionalobject[] See Localisation tab The set of regional settings for the datepicker fields. Entries are indexed by the country/region code with '' providing the default (English) settings. Each entry is an object with the properties shown on the Localisation tab. Language packages load new entries into this array and automatically apply them as global defaults.

<script type="text/javascript"
	src="jquery.calendars.picker-fr.js"></script>

If necessary, you can then revert to the default language settings with

$.calendars.picker.setDefaults($.calendars.picker.regional['']);

and apply the language settings to individual fields with code like the following, including localising the underlying calendar.

$('#frenchCalendar').calendarsPicker($.extend(
	{calendar: $.calendars.instance('gregorian', 'fr')},
	$.calendars.picker.regional['fr']));

Check out the list of available localisation packages.
Functions and Commands

changeDay | changeMonth | clear | destroy | disable | enable | errorPlacement | getDate | hide | isDisabled | isSelectable | multipleEvents | option (get) | option (set) | performAction | retrieveDate | selectDate | setDate | setDefaults | show | showMonth

SignatureReturnsComments
$.calendars.picker.setDefaults(settings)CalendarsPicker object Update the default instance settings to use with all datepicker instances.

settings (object) is the collection of new settings.

$.calendars.picker.setDefaults({dateFormat: 'yyyy-mm-dd'});
$(selector).calendarsPicker('option', settings)jQuery object Update the instance settings for the datepicker instance(s) attached to the given field(s).

settings (object) is the collection of new settings.

$(selector).calendarsPicker('option', {firstDay: 1});
$(selector).calendarsPicker('option', name, value)jQuery object Update a setting for the datepicker instance(s) attached to the given field(s).

name (string) is the name of the setting;

value (any) is the new value, or null to reset to the default.

$(selector).calendarsPicker('option', 'firstDay', 1);
$(selector).calendarsPicker('option', name)object or any Retrieve one or all of the current settings for the first datepicker instance attached to the given field(s).

name (string, optional) the name of the setting to retrieve; omit for all settings.

var settings = $(selector).calendarsPicker('option');
var firstDay = $(selector).calendarsPicker('option', 'firstDay');

Since 1.2.0 - previously you used the 'options' command.
$(selector).calendarsPicker('destroy')jQuery object Remove the datepicker functionality from the given field(s).
$(selector).calendarsPicker('enable')jQuery object Enable the datepicker for the given field(s) as well as the field itself.
$(selector).calendarsPicker('disable')jQuery object Disable the datepicker for the given field(s) as well as the field itself.
$(selector).calendarsPicker('isDisabled')boolean Determine whether the datepicker functionality has been disabled for the first of the given field(s).
$(selector).calendarsPicker('show')jQuery object Pop up the datepicker for the given field.
$(selector).calendarsPicker('hide')jQuery object Hide the datepicker for the given field.
$(selector).calendarsPicker('getDate') CDate[] Retrieve the currently selected date(s) from the datepicker for the first given field. An empty array is returned if no dates are selected. A date range datepicker always returns two dates, being the start and end of the range.

var dates = $(selector).calendarsPicker('getDate');
$(selector).calendarsPicker('setDate', dates)jQuery object Set the currently selected dates for the given field(s).

dates (CDate) is the new date, or (string) the date in the current date format, or (number) the number of days from today, or (string) a series of amounts and periods from today, or ([]) a collection of any of these formats. Provide an empty array to clear all dates or use the clear command.

$(selector).calendarsPicker('setDate', calendar.newDate(2009, 1, 26));
$(selector).calendarsPicker('setDate', '01/26/2009');
$(selector).calendarsPicker('setDate', '+1m'); // Today + 1 month
$(selector).calendarsPicker('setDate', 7); // Today + 7 days
$(selector).calendarsPicker('setDate',
	[calendar.newDate(2009, 1, 26), '+1m', 7]);
$(selector).calendarsPicker('setDate', startDate, endDate)jQuery object Set the currently selected date range for the given field(s).

startDate (see above) is the starting date for the date range.

endDate (see above) is the ending date for the date range.

$(selector).calendarsPicker('setDate',
	calendar.newDate(2009, 1, 26), calendar.newDate(2010, 1, 26));
$(selector).calendarsPicker('setDate', 7, '+1m');
$(selector).calendarsPicker('clear')jQuery object Clear the currently selected dates for the given field(s).
$(selector).calendarsPicker('isSelectable', date)boolean Determine whether a date is selectable for this datepicker. It checks against any minDate, maxDate, and/or onDate options that have been set.

date (CDate or string or number, optional) the date to check. This may be specified as an actual date (CDate), as a date string in the current dateFormat, as a number of days relative to today, or as a string of offsets and periods relative to today. For the last use 'y' for years, 'm' for months, 'w' for weeks, or 'd' for days. Multiple offsets may be combined in the one string. Omit to use the currently selected date, or today if none selected.

Since 1.1.2.
$(selector).calendarsPicker('performAction', name)jQuery object Execute a named command for a datepicker.

name (string) the name of the command.

$(selector).calendarsPicker('performAction', 'today');
$(selector).calendarsPicker('showMonth', year, month, day)jQuery object Change the displayed month to a specified month and year. If no month and year are given, today's month is shown.

year (number, optional) the year to show.

month (number, optional) the month to show.

day (number, optional) the day to highlight initially - if omitted it defaults to the previously highlighted day.

$(selector).calendarsPicker('showMonth', 2009, 1);
$(selector).calendarsPicker('changeMonth', offset)jQuery object Change the displayed month by moving a number of months ahead or behind.

offset (number) the number of months to move.

$(selector).calendarsPicker('changeMonth', -6);
$(selector).calendarsPicker('changeDay', offset)jQuery object Change the cursor day by moving a number of days ahead or behind.

offset (number) the number of days to move.

$(selector).calendarsPicker('changeDay', -14);
$(selector).calendarsPicker('retrieveDate', element) CDate Retrieve the date associated with a particular day element (a or span) within a datepicker.

element (element) the day element to extract the date from.
$(selector).calendarsPicker('selectDate', element)jQuery object Select the date associated with a particular day element (a or span) within a datepicker.

element (element) the day element to extract the date from.
$.calendars.picker.multipleEvents(fns)function Allow multiple event handlers to be triggered by a single callback. The handlers are called in the order specified.

fns (function...) is the collection of event handlers.

$(selector).calendarsPicker({
	onShow: $.calendars.picker.multipleEvents(
		$.calendars.picker.changeFirstDay, $.calendars.picker.showStatus)});
$.calendars.picker.errorPlacement(error, element)- Correctly places a validation error message after any trigger button or icon (or before it if using a right-to-left localisation). It should be assigned as the errorPlacement setting for the validate call. Only available with the validation extension.
Datepicker Extensions

The functions shown below are available through the picker.ext module. There are also several renderers available from this module.

changeFirstDay | highlightWeek | hoverCallback | monthNavigation | monthOnly | noWeekends | selectMonth | selectWeek | showStatus

SignatureReturnsComments
$.calendars.picker.noWeekendsobject Attach this function to the onDate setting to not allow the selection of days on weekends.

$(selector).calendarsPicker({
	onDate: $.calendars.picker.noWeekends});
$.calendars.picker.changeFirstDay- Attach this function to the onShow setting to allow the first day of the week to be changed by clicking on the day column headers.

$(selector).calendarsPicker({
	onShow: $.calendars.picker.changeFirstDay});
$.calendars.picker.hoverCallback(onHover)- Attach this function to the onShow setting to provide a callback when hovering over a day.

onHover (function) is the callback function that receives the current date (CDate) and a flag (boolean) indicating selectability as parameters on entry, and no parameters on exit, while this refers to the target input or division/span.

$(selector).calendarsPicker({
	onShow: $.calendars.picker.hoverCallback(showHover)});
	
function showHover(date, selectable) {
	$('#hoverOutput').text(
		(selectable ? date.formatDate() : null) || 'nothing');
}
$.calendars.picker.highlightWeek- Attach this function to the onShow setting to highlight the entire week when hovering over a day.

$(selector).calendarsPicker({
	onShow: $.calendars.picker.highlightWeek});
$.calendars.picker.monthOnly- Attach this function to the onShow setting to only allow selection of a month as a whole. The date returned is the first day of the chosen month.

$(selector).calendarsPicker({
	onShow: $.calendars.picker.monthOnly});


Since 1.0.1.
$.calendars.picker.showStatus- Attach this function to the onShow setting to show a status bar beneath the month(s) and to redirect tooltip information to that area.

$(selector).calendarsPicker({
	onShow: $.calendars.picker.showStatus});
$.calendars.picker.monthNavigation- Attach this function to the onShow setting to include links for each month above the month header to simplify navigation within a year.

$(selector).calendarsPicker({
    onShow: $.datepick.monthNavigation});

Since 1.1.1.
$.calendars.picker.selectWeek- Attach this function to the onShow setting to select the entire week when the associated week of the year entry is selected. You must use the weekOfYearRenderer for this to work, and the datepicker should be set as a date range.

$(selector).calendarsPicker({rangeSelect: true,
	renderer: $.calendars.picker.weekOfYearRenderer,
	onShow: $.calendars.picker.selectWeek});
$.calendars.picker.selectMonth- Attach this function to the onShow setting to select the entire month when the week of the year column header is selected. You must use the weekOfYearRenderer for this to work, and the datepicker should be set as a date range.

$(selector).calendarsPicker({rangeSelect: true,
	renderer: $.calendars.picker.weekOfYearRenderer,
	onShow: $.calendars.picker.selectMonth});
Validation Integration

The datepicker can be integrated with Jörn Zaefferer's validation plugin by adding the jquery.calendars.validation.js extension to your page.

Since 1.1.3 - combined validation rules into cpDate; previously there were also cpMinDate, cpMaxDate, and cpMinMaxDate, added cpCompareDate rule.

One new validation is defined (cpDate) for basic date validation. It automatically handles date ranges (including checking that the start date is not after the end date) and multiple dates, checks against any minDate and/or maxDate settings, and calls any onDate callback to verify selectability. It may be added as a class to your datepicker fields, or may be defined in the validate settings.

A second validation rule (cpCompareDate) lets you compare one date field with another date. This rule must be specified in the rules section of the validate call and be provided with a parameter to indicate the required comparison and the target date. Specify the comparison with any of the following: 'equal', 'eq', 'same', 'notEqual', 'ne', 'notSame', 'lessThan', 'lt', 'before', 'greaterThan', 'gt', 'after', 'notLessThan', 'ge', 'notBefore', 'notGreaterThan', 'le', 'notAfter'. Specify the target date as either the actual date (as a string in the current date format or a CDate object), as 'today', or as another datepicker field (as a jQuery selector, jQuery collection, or DOM element). The two parameters can be combined into one string (if the latter is a string), be given as items in an array, or be given as an object with a single attribute named for the comparison and with a value of the target.

$('form').validate({
	rules: {
		field1: {
			cpCompareDate: 'before 12/25/2010'
		},
		field2: {
			cpCompareDate: ['ne', $.calendars.instance().newDate(2010, 12, 25)]
		},
		field3: {
			cpCompareDate: {notLessThan: '#otherField'}
		}
	});

There is also a custom errorPlacement function defined so that the error messages appear after any trigger button or icon (or before it if using a right-to-left localisation).

You can customise the error messages via the datepicker defaults: $.calendars.picker.setDefaults({...}). The message fields are validateDate, validateDateMin, validateDateMax, validateDateMinMax, validateDateCompare, validateDateToday, validateDateOther, validateDateEQ, validateDateNE, validateDateLT, validateDateGT, validateDateLE, and validateDateGE. Within these messages '{n}' mark substitution points.

The sample page below show how the validations would be used. It defines three datepicker fields: one plain, one a date range, and one with a maximum limit. The validations are applied to the first and last by including the cpDate class on the fields. For the middle one the validation is defined in the validate call on the form, along with a required setting. Also note that a custom message is defined for the date range field.

<head>
<style type="text/css">@import "jquery.calendars.picker.css";</style>
<script type="text/javascript" src="js/jquery-1.4.4.js"></script>
<script type="text/javascript" src="js/jquery.validate.js"></script>
<script type="text/javascript" src="js/jquery.calendars.js"></script>
<script type="text/javascript" src="js/jquery.calendars.plus.js"></script>
<script type="text/javascript" src="js/jquery.calendars.picker.js"></script>
<script type="text/javascript" src="js/jquery.calendars.validation.js"></script>
<script type="text/javascript">
$(function() {
	$('#favDate').calendarsPicker();
	$('#holidayDates').calendarsPicker({rangeSelect: true});
	$('#birthDate').calendarsPicker({maxDate: 0});

	$('#validateForm').validate({
		errorPlacement: $.calendars.picker.errorPlacement,
		rules: {
			holidayDates: {
				required: true,
				cpDate: true
			}
		},
		messages: {
			holidayDates: 'Please enter a valid date range'
		}
	});
});
</script>
</head>
<body>
	<form id="validateForm">
		<p>Favourite date: <input type="text" id="favDate"
			name="favDate" size="10" class="cpDate"/></p>
		<p>Period of last holiday: <input type="text" id="holidayDates"
			name="holidayDates" size="24"/></p>
		<p>Date of birth: <input type="text" id="birthDate"
			name="birthDate" size="10" class="cpDate"/></p>
	</form>
</body>