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
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
|
||||||||||||||||||||
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> |
'<Prev' | Text for the previous month command. |
prevStatus |
string |
<optional> |
'Show the previous month' | Status text for the previous month command. |
prevJumpText |
string |
<optional> |
'<<' | Text for the previous year command. |
prevJumpStatus |
string |
<optional> |
'Show the previous year' | Status text for the previous year command. |
nextText |
string |
<optional> |
'Next>' | Text for the next month command. |
nextStatus |
string |
<optional> |
'Show the next month' | Status text for the next month command. |
nextJumpText |
string |
<optional> |
'>>' | 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> |
'  ▲' | Text for earlier years. |
laterText |
string |
<optional> |
'  ▼' | 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