jQuery Calendars Datepicker Reference

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.

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 | yearRange

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.

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.

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

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

Standard Renderers

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

Datepicker Globals

Functions and Commands

changeDay | changeMonth | clear | destroy | disable | enable | getDate | hide | isDisabled | multipleEvents | option | options | performAction | retrieveDate | selectDate | setDate | setDefaults | show | showMonth

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

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

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.

Four new validations are defined, as listed below. All automatically handle date ranges (including checking that the start date is not after the end date) and multiple dates. The first may be added as a class to your datepicker fields, while the others must be defined in the validate settings and be passed an empty array.

• cpDate - basic format validation
• cpMinDate - validation against a minimum date limit only
• cpMaxDate - validation against a maximum date limit only
• cpMinMaxDate - validation against minimum and maximum date limits

There is also a custom errorPlacement function defined so that the error messages appear after any trigger button or icon.

You can customise the error messages via the datepicker defaults: $.calendars.picker.setDefaults({...}). The message fields are validateDate, validateDateMin, validateDateMax, and validateDateMinMax. Within the latter use '{0}' and/or '{1}' for substituting in minimum/maximum date values.

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 two by including the cpDate class on the fields. For the last one the validation is defined in the validate call on the form, linking the field to the cpMaxDate rule. 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.3.2.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: {
			birthDate: {cpMaxDate: []}
		},
		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" class="cpDate"/></p>
		<p>Date of birth: <input type="text" id="birthDate"
			name="birthDate" size="10"/></p>
	</form>
</body>