.datepicker()
Categories: UI
.datepicker( [ options ] )
Plugin: jQuery.ui.datepicker
Description: Apply the Datepicker widget for each element in the set of matched elements
-
.datepicker( [ options ] )
version added: 1.0options A map of additional options pass to the widget.
The jQuery UI Datepicker is a highly configurable plugin that adds datepicker functionality to your pages. You can customize the date format and language, restrict the selectable date ranges and add in buttons and other navigation options easily.
By default, the datepicker calendar opens in a small overlay onFocus and closes automatically onBlur or when a date is selected. For an inline calendar, simply attach the datepicker to a div or span.
You can use keyboard shortcuts to drive the datepicker:
- page up/down - previous/next month
- ctrl+page up/down - previous/next year
- ctrl+home - current month or open when closed
- ctrl+left/right - previous/next day
- ctrl+up/down - previous/next week
- enter - accept the selected date
- ctrl+end - close and erase the date
- escape - close the datepicker without selection
Utility functions
- $.datepicker.setDefaults( settings ) - Set settings for all datepicker instances.
- $.datepicker.formatDate( format, date, settings ) - Format a date into a string value with a specified format.
- $.datepicker.parseDate( format, value, settings ) - Extract a date from a string value with a specified format.
- $.datepicker.iso8601Week( date ) - Determine the week of the year for a given date: 1 to 53.
- $.datepicker.noWeekends - Set as beforeShowDay function to prevent selection of weekends.
Localization
Datepicker provides support for localizing its content to cater for different languages
and date formats. Each localization is contained within its own file with the
language code appended to the name, e.g. jquery.ui.datepicker-fr.js
for French.
The desired localization file should be included after the main datepicker code. They add their settings to the set
of available localizations and automatically apply them as defaults for all instances.
The $.datepicker.regional
attribute holds an array of localizations,
indexed by language code, with '' referring to the default (English). Each entry is
an object with the following attributes: closeText
, prevText
,
nextText
, currentText
, monthNames
,
monthNamesShort
, dayNames
, dayNamesShort
,
dayNamesMin
, weekHeader
, dateFormat
,
firstDay
, isRTL
, showMonthAfterYear
,
and yearSuffix
.
You can restore the default localizations with:
$.datepicker.setDefaults($.datepicker.regional['']);
And can then override an individual datepicker for a specific locale:
$(selector).datepicker($.datepicker.regional['fr']);
-
create
This event is triggered when datepicker is created.
-
beforeShow
Can be a function that takes an input field and current datepicker instance and returns an options object to update the datepicker with. It is called just before the datepicker is displayed.
-
beforeShowDay
The function takes a date as a parameter and must return an array with [0] equal to true/false indicating whether or not this date is selectable, [1] equal to a CSS class name(s) or '' for the default presentation, and [2] an optional popup tooltip for this date. It is called for each day in the datepicker before it is displayed.
-
onChangeMonthYear
Allows you to define your own event when the datepicker moves to a new month and/or year. The function receives the selected year, month (1-12), and the datepicker instance as parameters.
this
refers to the associated input field. -
onClose
Allows you to define your own event when the datepicker is closed, whether or not a date is selected. The function receives the selected date as text ('' if none) and the datepicker instance as parameters.
this
refers to the associated input field. -
onSelect
Allows you to define your own event when the datepicker is selected. The function receives the selected date as text and the datepicker instance as parameters.
this
refers to the associated input field.
-
destroy
-
.datepicker( "destroy" )
version added: 1.0
Remove the datepicker functionality completely. This will return the element back to its pre-init state.
-
-
disable
-
.datepicker( "disable" )
version added: 1.0
Disable the datepicker.
-
-
enable
-
.datepicker( "enable" )
version added: 1.0
Enable the datepicker.
-
-
option
-
.datepicker( "option" , optionName , [value] )
version added: 1.0
Get or set any datepicker option. If no value is specified, will act as a getter.
-
-
option
-
.datepicker( "option" , options )
version added: 1.0
Set multiple datepicker options at once by providing an options object.
-
-
widget
-
.datepicker( "widget" )
version added: 1.0
Returns the .ui-datepicker element.
-
-
dialog
-
.datepicker( "dialog" , date , [onSelect] , [settings] , [pos] )
version added: 1.0
Open a datepicker in a "dialog" box.
dateText: the initial date for the date picker as either a Date or a string in the current date format.
onSelect: A callback function when a date is selected. The function receives the date text and date picker instance as parameters.
settings: The new settings for the date picker.
pos: The position of the top/left of the dialog as [x, y] or a MouseEvent that contains the coordinates. If not specified the dialog is centered on the screen.
-
-
isDisabled
-
.datepicker( "isDisabled" )
version added: 1.0
Determine whether a date picker has been disabled.
-
-
hide
-
.datepicker( "hide" )
version added: 1.0
Close a previously opened date picker.
-
-
show
-
.datepicker( "show" )
version added: 1.0
Call up a previously attached date picker.
-
-
refresh
-
.datepicker( "refresh" )
version added: 1.0
Redraw a date picker, after having made some external modifications.
-
-
getDate
-
.datepicker( "getDate" )
version added: 1.0
Returns the current date for the datepicker or null if no date has been selected.
-
-
setDate
-
.datepicker( "setDate" , date )
version added: 1.0
Sets the current date for the datepicker. The new date may be a Date object or a string in the current date format (e.g. '01/26/2009'), a number of days from today (e.g. +7) or a string of values and periods ('y' for years, 'm' for months, 'w' for weeks, 'd' for days, e.g. '+1m +7d'), or null to clear the selected date.
-
.datepicker( [ options ] )Returns: jQuery
Plugin: jQuery.ui.datepicker
Description: Apply the Datepicker widget for each element in the set of matched elements
-
.datepicker( [ options ] )
version added: 1.2options A map of additional options pass to the widget.
In jQuery SDK are additional options available for the .datepicker()
widget compared to the standard from jQuery UI.
The region
option is based on the jQuery.i18n
plugin.
Using the region
option will set the following options automatically:
- dayNames
- dayNamesMin
- dayNamesShort
- monthNames
- monthNamesShort
- firstDay
- shortYearCutoff
- dateFormat