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, Nanakshahi, Mayan, and Discworld.
$(selector).calendarsPicker({calendar:
$.calendars.instance('persian', 'fa')});
|
pickerClass | string | '' |
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'});
|
showOnFocus | boolean | true |
When true a popup datepicker appears for an input
field when it gains focus. When false you should
specify a showTrigger instead. |
showTrigger | string or element or jQuery | null |
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'});
|
showAnim | string | '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
|
showOptions | object | {} |
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'}});
|
showSpeed | string 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});
|
string or element or jQuery | null |
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'});
|
alignment | string | '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. |
fixedWeeks | boolean | false |
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. |
firstDay | number | null |
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. |
calculateWeek | function | null |
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;
}
|
localNumbers | boolean | false |
Set to true to use localised characters for date numbers (where available -
see the Calendar digits setting),
or false to always use standard Arabic numerals.
Since 2.0.2. |
monthsToShow | number 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]});
|
monthsOffset | number | 0 |
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});
|
monthsToStep | number | 1 |
The number of months to move when the
previous or next
month commands are invoked. |
monthsToJump | number | 12 |
The number of months to move when the
previous or next
year commands are invoked. |
useMouseWheel | boolean | true |
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. |
changeMonth | boolean | true |
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. |
yearRange | string | '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. |
showOtherMonths | boolean | false |
Set to true to show the days in other months that
appear in the partial weeks before or after the current month. |
selectOtherMonths | boolean | false |
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 string | null |
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'});
|
selectDefaultDate | boolean | false |
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 string | null |
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 string | null |
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'});
|
dateFormat | string | null |
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 day number
- @ - 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});
|
autoSize | boolean | false |
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. |
rangeSelect | boolean | false |
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. |
rangeSeparator | string | ' - ' |
Specify the separator shown between the two dates in a
date range. |
multiSelect | number | 0 |
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. |
multiSeparator | string | ',' |
Specify the separator shown between the dates selected in a
multiple date datepicker. |
onDate | function | null |
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'};
}
});
|
onShow | function | null |
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');
}
});
|
onChangeMonthYear | function | null |
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);
}
});
|
onSelect | function | null |
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());
}
});
|
onClose | function | null |
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));
}
});
|
altField | string or element or jQuery | null |
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'});
|
altFormat | string | null |
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. |
constrainInput | boolean | true |
Set to true to only allow the entry of characters
specified by the dateFormat ,
or false to allow any characters. |
commandsAsDateFormat | boolean | false |
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 >'});
|
commands | object | $.calendars.picker.commands |
See the
Commands tab for more details. |