Class: CalendarsPicker

CalendarsPicker

new CalendarsPicker()

Create the calendars datepicker plugin.

Sets an input field to popup a calendar for date entry, or a div or span to show an inline calendar.

Expects HTML like:

<input type="text"> or <div></div>

Provide inline configuration like:

<input type="text" data-calendarsPicker="name: 'value'"/>
Source:
Example
$(selector).calendarsPicker()
$(selector).calendarsPicker({minDate: 0, maxDate: '+1m +1w'})

Extends

  • JQPlugin

Members

(static) commands

Command actions that may be added to a layout by name.
  • prev - Show the previous month (based on monthsToStep option) - PageUp
  • prevJump - Show the previous year (based on monthsToJump option) - Ctrl+PageUp
  • next - Show the next month (based on monthsToStep option) - PageDown
  • nextJump - Show the next year (based on monthsToJump option) - Ctrl+PageDown
  • current - Show the currently selected month or today's if none selected - Ctrl+Home
  • today - Show today's month - Ctrl+Home
  • clear - Erase the date and close the datepicker popup - Ctrl+End
  • close - Close the datepicker popup - Esc
  • prevWeek - Move the cursor to the previous week - Ctrl+Up
  • prevDay - Move the cursor to the previous day - Ctrl+Left
  • nextDay - Move the cursor to the next day - Ctrl+Right
  • nextWeek - Move the cursor to the next week - Ctrl+Down
The command name is the key name and is used to add the command to a layout with '{button:name}' or '{link:name}'. Each has the following attributes.
Properties:
Name Type Description
text string The field in the regional settings for the displayed text.
status string The field in the regional settings for the status text.
keystroke object The keystroke to trigger the action, with attributes:
Properties
Name Type Attributes Description
keyCode number the code for the keystroke,
ctrlKey boolean <optional>
true if Ctrl is required,
altKey boolean <optional>
true if Alt is required,
shiftKey boolean <optional>
true if Shift is required.
enabled CalendarsPickerCommandEnabled The function that indicates the command is enabled.
date CalendarsPickerCommandDate The function to get the date associated with this action.
action CalendarsPickerCommandAction The function that implements the action.
Source:

(static) defaultOptions

Default settings for the plugin.
Properties:
Name Type Attributes Default Description
calendar Calendar <optional>
$.calendars.instance() The calendar for this datepicker.
pickerClass string <optional>
'' CSS class to add to this instance of the datepicker.
showOnFocus boolean <optional>
true true for popup on focus, false for not.
showTrigger string | Element | jQuery <optional>
null Element to be cloned for a trigger, null for none.
showAnim string <optional>
'show' Name of jQuery animation for popup, '' for no animation.
showOptions object <optional>
null Options for enhanced animations.
showSpeed string | number <optional>
'normal' Duration of display/closure, named or in milliseconds.
popupContainer string | Element | jQuery <optional>
null The element to which a popup calendar is added, null for body.
alignment string <optional>
'bottom' Alignment of popup - with nominated corner of input: 'top' or 'bottom' aligns depending on language direction, 'topLeft', 'topRight', 'bottomLeft', 'bottomRight'.
fixedWeeks boolean <optional>
false true to always show 6 weeks, false to only show as many as are needed.
firstDay number <optional>
null First day of the week, 0 = Sunday, 1 = Monday, etc., null for calendar default.
calculateWeek CalendarsPickerCalculateWeek <optional>
null Calculate week of the year from a date, null for calendar default.
localNumbers boolean <optional>
false true to localise numbers (if available), false to use normal Arabic numerals.
monthsToShow number | Array.<number> <optional>
1 How many months to show, cols or [rows, cols].
monthsOffset number <optional>
0 How many months to offset the primary month by; may be a function that takes the date and returns the offset.
monthsToStep number <optional>
1 How many months to move when prev/next clicked.
monthsToJump number <optional>
12 How many months to move when large prev/next clicked.
useMouseWheel boolean <optional>
true true to use mousewheel if available, false to never use it.
changeMonth boolean <optional>
true true to change month/year via drop-down, false for navigation only.
yearRange string <optional>
'c-10:c+10' Range of years to show in drop-down: 'any' for direct text entry or 'start:end', where start/end are '+-nn' for relative to today or 'c+-nn' for relative to the currently selected date or 'nnnn' for an absolute year.
showOtherMonths boolean <optional>
false true to show dates from other months, false to not show them.
selectOtherMonths boolean <optional>
false true to allow selection of dates from other months too.
defaultDate string | number | CDate <optional>
null Date to show if no other selected.
selectDefaultDate boolean <optional>
false true to pre-select the default date if no other is chosen.
minDate string | number | CDate <optional>
null The minimum selectable date.
maxDate string | number | CDate <optional>
null The maximum selectable date.
dateFormat string <optional>
'mm/dd/yyyy' Format for dates.
autoSize boolean <optional>
false true to size the input field according to the date format.
rangeSelect boolean <optional>
false Allows for selecting a date range on one date picker.
rangeSeparator string <optional>
' - ' Text between two dates in a range.
multiSelect number <optional>
0 Maximum number of selectable dates, zero for single select.
multiSeparator string <optional>
',' Text between multiple dates.
onDate CalendarsPickerOnDate <optional>
null Callback as a date is added to the datepicker.
onShow CalendarsPickerOnShow <optional>
null Callback just before a datepicker is shown.
onChangeMonthYear CalendarsPickerOnChangeMonthYear <optional>
null Callback when a new month/year is selected.
onSelect CalendarsPickerOnSelect <optional>
null Callback when a date is selected.
onClose CalendarsPickerOnClose <optional>
null Callback when a datepicker is closed.
altField string | Element | jQuery <optional>
null Alternate field to update in synch with the datepicker.
altFormat string <optional>
null Date format for alternate field, defaults to dateFormat.
constrainInput boolean <optional>
true true to constrain typed input to dateFormat allowed characters.
commandsAsDateFormat boolean <optional>
false true to apply formatDate to the command texts.
commands object <optional>
this.commands Command actions that may be added to a layout by name.
Source:
Example
$(selector).calendarsPicker({calendar: $.calendars.instance('persian')})
$(selector).calendarsPicker({monthsToShow: [2, 3], monthsToStep: 6})
$(selector).calendarsPicker({minDate: $.calendars.newDate(2001, 1, 1),
  maxDate: $.calendars.newDate(2010, 12, 31)})

(static) defaultRenderer

Default template for generating a datepicker. Insert anywhere:
  • '{l10n:name}' to insert localised value for name,
  • '{link:name}' to insert a link trigger for command name,
  • '{button:name}' to insert a button trigger for command name,
  • '{popup:start}...{popup:end}' to mark a section for inclusion in a popup datepicker only,
  • '{inline:start}...{inline:end}' to mark a section for inclusion in an inline datepicker only.
Properties:
Name Type Description
picker string Overall structure: '{months}' to insert calendar months.
monthRow string One row of months: '{months}' to insert calendar months.
month string A single month: '{monthHeader:dateFormat}' to insert the month header - dateFormat is optional and defaults to 'MM yyyy', '{weekHeader}' to insert a week header, '{weeks}' to insert the month's weeks.
weekHeader string A week header: '{days}' to insert individual day names.
dayHeader string Individual day header: '{day}' to insert day name.
week string One week of the month: '{days}' to insert the week's days, '{weekOfYear}' to insert week of year.
day string An individual day: '{day}' to insert day value.
monthSelector string jQuery selector, relative to picker, for a single month.
daySelector string jQuery selector, relative to picker, for individual days.
rtlClass string Class for right-to-left (RTL) languages.
multiClass string Class for multi-month datepickers.
defaultClass string Class for selectable dates.
selectedClass string Class for currently selected dates.
highlightedClass string Class for highlighted dates.
todayClass string Class for today.
otherMonthClass string Class for days from other months.
weekendClass string Class for days on weekends.
commandClass string Class prefix for commands.
commandButtonClass string Extra class(es) for commands that are buttons.
commandLinkClass string Extra class(es) for commands that are links.
disabledClass string Class for disabled commands.
Source:

(static) name

The name of the plugin.
Default Value:
  • 'calendarsPicker'
Source:

(static) regionalOptions

Localisations for the plugin. Entries are objects indexed by the language code ('' being the default US/English). Each object has the following attributes.
Properties:
Name Type Attributes Default Description
renderer string <optional>
this.defaultRenderer The rendering templates.
prevText string <optional>
'&lt;Prev' Text for the previous month command.
prevStatus string <optional>
'Show the previous month' Status text for the previous month command.
prevJumpText string <optional>
'&lt;&lt;' Text for the previous year command.
prevJumpStatus string <optional>
'Show the previous year' Status text for the previous year command.
nextText string <optional>
'Next&gt;' Text for the next month command.
nextStatus string <optional>
'Show the next month' Status text for the next month command.
nextJumpText string <optional>
'&gt;&gt;' Text for the next year command.
nextJumpStatus string <optional>
'Show the next year' Status text for the next year command.
currentText string <optional>
'Current' Text for the current month command.
currentStatus string <optional>
'Show the current month' Status text for the current month command.
todayText string <optional>
'Today' Text for the today's month command.
todayStatus string <optional>
'Show today\'s month' Status text for the today's month command.
clearText string <optional>
'Clear' Text for the clear command.
clearStatus string <optional>
'Clear all the dates' Status text for the clear command.
closeText string <optional>
'Close' Text for the close command.
closeStatus string <optional>
'Close the datepicker' Status text for the close command.
yearStatus string <optional>
'Change the year' Status text for year selection.
earlierText string <optional>
'&#160;&#160;▲' Text for earlier years.
laterText string <optional>
'&#160;&#160;▼' Text for later years.
monthStatus string <optional>
'Change the month' Status text for month selection.
weekText string <optional>
'Wk' Text for week of the year column header.
weekStatus string <optional>
'Week of the year' Status text for week of the year column header.
dayStatus string <optional>
'Select DD, M d, yyyy' Status text for selectable days.
defaultStatus string <optional>
'Select a date' Status text shown by default.
isRTL boolean <optional>
false true if language is right-to-left.
Source:

(static) themeRollerRenderer

ThemeRoller template for generating a calendar picker. Used with the renderer regional option.
Source:
Example
renderer: $.calendarsPicker.themeRollerRenderer

(static) themeRollerWeekOfYearRenderer

ThemeRoller template for generating a calendar picker showing week of year. Used with the renderer regional option.
Source:
Example
renderer: $.calendarsPicker.themeRollerWeekOfYearRenderer

(static) weekOfYearRenderer

Template for generating a calendar picker showing week of year. Used with the renderer regional option.
Source:
Example
renderer: $.calendarsPicker.weekOfYearRenderer

Methods

(static) changeDay(elem, offset)

Adjust the currently shown day.
Parameters:
Name Type Description
elem Element The control to affect.
offset number The number of days to change by.
Source:
Example
$(selector).datepick('changeDay', 7)

(static) changeFirstDay(picker)

Change the first day of the week by clicking on the day header. Used with the onShow option.
Parameters:
Name Type Description
picker jQuery The completed datepicker division.
Source:
Example
onShow: $.calendarsPicker.changeFirstDay

(static) changeMonth(elem, offset)

Adjust the currently shown month.
Parameters:
Name Type Description
elem Element The control to affect.
offset number The number of months to change by.
Source:
Example
$(selector).datepick('changeMonth', 2)

(static) clear(elem)

Clear an input and close a popup datepicker.
Parameters:
Name Type Description
elem Element The control to use.
Source:
Example
$(selector).datepick('clear')

(static) disable(elem)

Disable the control.
Parameters:
Name Type Description
elem Element The control to affect.
Source:
Example
$(selector).datepick('disable')

(static) enable(elem)

Enable the control.
Parameters:
Name Type Description
elem Element The control to affect.
Source:
Example
$(selector).datepick('enable')

(static) errorFormat(source, params) → {string}

Format a validation error message involving dates. For use in $.validator.addMethod.
Parameters:
Name Type Description
source string The error message.
params Array.<CDate> The dates.
Source:
Returns:
The formatted message.
Type
string

(static) errorPlacement(error, elem)

Correct error placement for validation errors - after any trigger.
Parameters:
Name Type Description
error jQuery The error message.
elem jQuery The field in error.
Source:
Example
$('form').validate({
  errorPlacement: $.calendarsPicker.errorPlacement,
  ...
});

(static) getDate(elem) → {Array.<CDate>}

Retrieve the selected date(s) for a datepicker.
Parameters:
Name Type Description
elem Element The control to examine.
Source:
Returns:
The selected date(s).
Type
Array.<CDate>
Example
var dates = $(selector).datepick('getDate')

(static) hide(elem, immediate)

Hide a popup datepicker.
Parameters:
Name Type Description
elem Element | object The control to use or the current instance settings.
immediate boolean true to close immediately without animation (internal).
Source:
Example
$(selector).datepick('hide')

(static) highlightWeek(picker, calendar, inst)

Highlight the entire week when hovering over it. Used with the onShow option.
Parameters:
Name Type Description
picker jQuery The completed datepicker division.
calendar BaseCalendar The calendar implementation.
inst object The current instance settings.
Source:
Example
onShow: $.calendarsPicker.highlightWeek

(static) hoverCallback(onHover)

Add a callback when hovering over dates. Used with the onShow option.
Parameters:
Name Type Description
onHover CalendarsPickerOnHover The callback when hovering.
Source:
Example
onShow: $.calendarsPicker.hoverCallback(showHovered)

(static) isDisabled(elem) → {boolean}

Is the first field in a jQuery collection disabled as a datepicker?
Parameters:
Name Type Description
elem Element The control to examine.
Source:
Returns:
true if disabled, false if enabled.
Type
boolean
Example
if ($(selector).datepick('isDisabled')) {...}

(static) monthNavigation(picker, calendar, inst)

Allow easier navigation by month. Used with the onShow option.
Parameters:
Name Type Description
picker jQuery The completed datepicker division.
calendar BaseCalendar The calendar implementation.
inst object The current instance settings.
Source:
Example
onShow: $.calendarsPicker.monthNavigation

(static) monthOnly(picker, calendar)

Select a month only instead of a single day. Used with the onShow option.
Parameters:
Name Type Description
picker jQuery The completed datepicker division.
calendar BaseCalendar The calendar implementation.
Source:
Example
onShow: $.calendarsPicker.monthOnly

(static) multipleEvents(fns)

Apply multiple event functions.
Parameters:
Name Type Description
fns function The functions to apply.
Source:
Example
onShow: multipleEvents(fn1, fn2, ...)

(static) noWeekends(date) → {object}

Don't allow weekends to be selected. Used with the onDate option.
Parameters:
Name Type Description
date CDate The current date.
Source:
Returns:
Information about this date.
Type
object
Example
onDate: $.calendarsPicker.noWeekends

(static) performAction(elem, action)

Perform a named action for a datepicker.
Parameters:
Name Type Description
elem element The control to affect.
action string The name of the action.
Source:
Example
$(selector).calendarsPicker('performAction', 'next')

(static) retrieveDate(elem, target) → {CDate}

Retrieve the date associated with an entry in the datepicker.
Parameters:
Name Type Description
elem Element The control to examine.
target Element The selected datepicker element.
Source:
Returns:
The corresponding date, or null.
Type
CDate
Example
var date = $(selector).datepick('retrieveDate',
  $('div.datepick-popup a:contains(10)')[0])

(static) selectDate(elem, target)

Select a date for this datepicker.
Parameters:
Name Type Description
elem Element The control to examine.
target Element The selected datepicker element.
Source:
Example
$(selector).datepick('selectDate', $('div.datepick-popup a:contains(10)')[0])

(static) selectDate(elem, target)

Trigger a validation after updating the input field with the selected date.
Parameters:
Name Type Description
elem Element The control to examine.
target Element The selected datepicker element.
Source:

(static) selectMonth(picker, calendar, inst)

Select an entire month when clicking on the week header. Use in conjunction with weekOfYearRenderer. Used with the onShow option.
Parameters:
Name Type Description
picker jQuery The completed datepicker division.
calendar BaseCalendar The calendar implementation.
inst object The current instance settings.
Source:
Example
onShow: $.calendarsPicker.selectMonth

(static) selectWeek(picker, calendar, inst)

Select an entire week when clicking on a week number. Use in conjunction with weekOfYearRenderer. Used with the onShow option.
Parameters:
Name Type Description
picker jQuery The completed datepicker division.
calendar BaseCalendar The calendar implementation.
inst object The current instance settings.
Source:
Example
onShow: $.calendarsPicker.selectWeek

(static) setDate(elem, dates, endDateopt, keyUpopt, setOptopt)

Set the selected date(s) for a datepicker.
Parameters:
Name Type Attributes Description
elem Element The control to examine.
dates CDate | number | string | array The selected date(s).
endDate CDate | number | string <optional>
The ending date for a range.
keyUp boolean <optional>
true if coming from keyUp processing (internal).
setOpt boolean <optional>
true if coming from option processing (internal).
Source:
Example
$(selector).datepick('setDate', new Date(2014, 12-1, 25))
$(selector).datepick('setDate', '12/25/2014', '01/01/2015')
$(selector).datepick('setDate', [date1, date2, date3])

(static) show(elem)

Show a popup datepicker.
Parameters:
Name Type Description
elem Event | Element a focus event or the control to use.
Source:
Example
$(selector).datepick('show')

(static) showMonth(elem, yearopt, monthopt, dayopt)

Set the currently shown month, defaulting to today's.
Parameters:
Name Type Attributes Description
elem Element The control to affect.
year number <optional>
The year to show.
month number <optional>
The month to show (calendar minimum month to maximum month).
day number <optional>
The day to show.
Source:
Example
$(selector).datepick('showMonth', 2014, 12, 25)

(static) showStatus(picker, calendar, inst)

Show a status bar with messages. Used with the onShow option.
Parameters:
Name Type Description
picker jQuery The completed datepicker division.
calendar BaseCalendar The calendar implementation.
inst object The current instance settings.
Source:
Example
onShow: $.calendarsPicker.showStatus