Categories

.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.0

    options   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

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']);

The localization files are also available in the UI svn:
http://jquery-ui.googlecode.com/svn/trunk/ui/i18n/
  • disabled

    Disables (true) or enables (false) the datepicker. Can be set when initialising (first creating) the datepicker.

    Default: false

  • altField

    The jQuery selector for another field that is to be updated with the selected date from the datepicker. Use the altFormat setting to change the format of the date within this field. Leave as blank for no alternate field.

    Default: ''

  • altFormat

    The dateFormat to be used for the altField option. This allows one date format to be shown to the user for selection purposes, while a different format is actually sent behind the scenes. For a full list of the possible formats see the formatDate function

    Default: ''

  • appendText

    The text to display after each date field, e.g. to show the required format.

    Default: ''

  • autoSize

    Set to true to automatically resize the input field to accommodate dates in the current dateFormat.

    Default: false

  • buttonImage

    The URL for the popup button image. If set, buttonText becomes the alt value and is not directly displayed.

    Default: ''

  • buttonImageOnly

    Set to true to place an image after the field to use as the trigger without it appearing on a button.

    Default: false

  • buttonText

    The text to display on the trigger button. Use in conjunction with showOn equal to 'button' or 'both'.

    Default: '...'

  • calculateWeek

    A function to calculate the week of the year for a given date. The default implementation uses the ISO 8601 definition: weeks start on a Monday; the first week of the year contains the first Thursday of the year.

    Default: $.datepicker.iso8601Week

  • changeMonth

    Allows you to change the month by selecting from a drop-down list. You can enable this feature by setting the attribute to true.

    Default: false

  • changeYear

    Allows you to change the year by selecting from a drop-down list. You can enable this feature by setting the attribute to true. Use the yearRange option to control which years are made available for selection.

    Default: false

  • closeText

    The text to display for the close link. This attribute is one of the regionalisation attributes. Use the showButtonPanel to display this button.

    Default: 'Done'

  • constrainInput

    When true entry in the input field is constrained to those characters allowed by the current dateFormat.

    Default: true

  • currentText

    The text to display for the current day link. This attribute is one of the regionalisation attributes. Use the showButtonPanel to display this button.

    Default: 'Today'

  • dateFormat

    The format for parsed and displayed dates. This attribute is one of the regionalisation attributes. For a full list of the possible formats see the formatDate function.

    Default: 'mm/dd/yy'

  • dayNames

    The list of long day names, starting from Sunday, for use as requested via the dateFormat setting. They also appear as popup hints when hovering over the corresponding column headings. This attribute is one of the regionalisation attributes.

    Default: ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday']

  • dayNamesMin

    The list of minimised day names, starting from Sunday, for use as column headers within the datepicker. This attribute is one of the regionalisation attributes.

    Default: ['Su', 'Mo', 'Tu', 'We', 'Th', 'Fr', 'Sa']

  • dayNamesShort

    The list of abbreviated day names, starting from Sunday, for use as requested via the dateFormat setting. This attribute is one of the regionalisation attributes.

    Default: ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat']

  • defaultDate

    Set the date to highlight on first opening if the field is blank. Specify either an actual date via a Date object or as a string in the current dateFormat, or 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 for today.

    Default: null

  • duration

    Control the speed at which the datepicker appears, it may be a time in milliseconds or a string representing one of the three predefined speeds ("slow", "normal", "fast").

    Default: 'normal'

  • firstDay

    Set the first day of the week: Sunday is 0, Monday is 1, ... This attribute is one of the regionalisation attributes.

  • gotoCurrent

    When true the current day link moves to the currently selected date instead of today.

    Default: false

  • hideIfNoPrevNext

    Normally the previous and next links are disabled when not applicable (see minDate/maxDate). You can hide them altogether by setting this attribute to true.

    Default: false

  • isRTL

    True if the current language is drawn from right to left. This attribute is one of the regionalisation attributes.

    Default: false

  • maxDate

    Set a maximum selectable date via a Date object or as a string in the current dateFormat, or 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 +1w'), or null for no limit.

    Default: null

  • minDate

    Set a minimum selectable date via a Date object or as a string in the current dateFormat, or 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. '-1y -1m'), or null for no limit.

    Default: null

  • monthNames

    The list of full month names, for use as requested via the dateFormat setting. This attribute is one of the regionalisation attributes.

    Default: ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December']

  • monthNamesShort

    The list of abbreviated month names, as used in the month header on each datepicker and as requested via the dateFormat setting. This attribute is one of the regionalisation attributes.

    Default: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']

  • navigationAsDateFormat

    When true the formatDate function is applied to the prevText, nextText, and currentText values before display, allowing them to display the target month names for example.

    Default: false

  • nextText

    The text to display for the next month link. This attribute is one of the regionalisation attributes. With the standard ThemeRoller styling, this value is replaced by an icon.

    Default: 'Next'

  • numberOfMonths

    Set how many months to show at once. The value can be a straight integer, or can be a two-element array to define the number of rows and columns to display.

    Default: 1

  • prevText

    The text to display for the previous month link. This attribute is one of the regionalisation attributes. With the standard ThemeRoller styling, this value is replaced by an icon.

    Default: 'Prev'

  • selectOtherMonths

    When true days in other months shown before or after the current month are selectable. This only applies if showOtherMonths is also true.

    Default: false

  • shortYearCutoff

    Set the cutoff year for determining the century for a date (used in conjunction with dateFormat 'y'). If a numeric value (0-99) is provided then this value is used directly. If a string value is provided then it is converted to a number and added to the current year. Once the cutoff year is calculated, any dates entered with a year value less than or equal to it are considered to be in the current century, while those greater than it are deemed to be in the previous century.

    Default: '+10'

  • showAnim

    Set the name of the animation used to show/hide the datepicker. Use 'show' (the default), 'slideDown', 'fadeIn', any of the show/hide jQuery UI effects, or '' for no animation.

    Default: 'show'

  • showButtonPanel

    Whether to show the button panel.

    Default: false

  • showCurrentAtPos

    Specify where in a multi-month display the current month shows, starting from 0 at the top/left.

  • showMonthAfterYear

    Whether to show the month after the year in the header. This attribute is one of the regionalisation attributes.

    Default: false

  • showOn

    Have the datepicker appear automatically when the field receives focus ('focus'), appear only when a button is clicked ('button'), or appear when either event takes place ('both').

    Default: 'focus'

  • showOptions

    If using one of the jQuery UI effects for showAnim, you can provide additional settings for that animation via this option.

    Default: {}

  • showOtherMonths

    Display dates in other months (non-selectable) at the start or end of the current month. To make these days selectable use selectOtherMonths.

    Default: false

  • showWeek

    When true a column is added to show the week of the year. The calculateWeek option determines how the week of the year is calculated. You may also want to change the firstDay option.

    Default: false

  • stepMonths

    Set how many months to move when clicking the Previous/Next links.

    Default: 1

  • weekHeader

    The text to display for the week of the year column heading. This attribute is one of the regionalisation attributes. Use showWeek to display this column.

    Default: 'Wk'

  • yearRange

    Control the range of years displayed in the year drop-down: either relative to today's year (-nn:+nn), relative to the currently selected year (c-nn:c+nn), absolute (nnnn:nnnn), or combinations of these formats (nnnn:-nn). Note that this option only affects what appears in the drop-down, to restrict which dates may be selected use the minDate and/or maxDate options.

    Default: 'c-10:c+10'

  • yearSuffix

    Additional text to display after the year in the month headers. This attribute is one of the regionalisation attributes.

    Default: ''

  • 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.2

    options   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
  • region

    A combination of an ISO 639 two-letter lowercase culture code for the language (and a two-letter uppercase code for the country or region).