A separate datepicker instance is created for each targeted control:
$(selector).datepick();
.
When applied to a div
or span
the datepicker
is rendered inline. Otherwise it appears as a popup on demand.
Each instance may have different settings, e.g.
$(selector).datepick({minDate: new Date()});
Alternately, you can specify the settings per control by adding a data-datepick
attribute, e.g.
<input type="text" data-datepick="rangeSelect: true, minDate: 'new Date()'"/>
The datepicker functionality can only be applied once. Affected controls are flagged
with the is-datepick
class and are not re-processed if targeted again.
Use the option
command if you want to change settings after the initial setup.
Below are the settings that may be applied to each datepicker instance. All are optional.
A note on Date - the JavaScript Date
constructor expects
the year, month, and day as parameters. However, the month ranges from 0 to 11.
To make explicit what date is intended (does a month of 3 mean March or April?)
I specify the month from 1 to 12 and manually subtract the 1.
Thus the following denotes 25 December, 2014.
$(selector).datepick({minDate: new Date(2014, 12-1, 25)});
alignment | altField | altFormat | autoSize | calculateWeek | changeMonth | commands | commandsAsDateFormat | constrainInput | defaultDate | fixedWeeks | maxDate | minDate | monthsOffset | monthsToJump | monthsToShow | monthsToStep | multiSelect | multiSeparator | onChangeMonthYear | onClose | onDate | onSelect | onShow | pickerClass | popupContainer | rangeSelect | rangeSeparator | selectDefaultDate | selectOtherMonths | shortYearCutoff | showAnim | showOnFocus | showOptions | showOtherMonths | showSpeed | showTrigger | useMouseWheel | yearRange
Name | Type | Default | Comments |
---|---|---|---|
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.
Since 4.0.0. |
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.Since 4.0.0 - previously incorporated into showOn . |
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).
Since 4.0.0 - previously you used showOn , buttonText , buttonImage ,
and buttonImageOnly . |
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.
Since 3.7.3 - '' for no animation. |
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.
|
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.
Since 4.0.0 - previously it was duration . |
popupContainer | 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.
Since 4.0.0. |
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 'bottomRight'.
The first two options will reposition the datepicker if it does not
fit in the requested space. Since 3.7.0. |
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.Since 4.0.0. |
calculateWeek | function | $.datepick. iso8601Week | A function to calculate the week of the year for a given date.
The date (Date) is passed as a parameter and the function returns
a number indicating the corresponding week of the year.
If set to null the built-in
ISO 8601 calculation is used.
You should use the
weekOfYearRenderer to actually display the value.
|
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.
Since 4.0.0 - previously it was numberOfMonths .Since 4.0.1 - mark first and last months in each row with classes first and last . |
monthsOffset | number or function | 0 | When showing multiple months, this setting
indicates at which position the current month is shown, starting from
zero. If specified as a function, it accepts a date as its parameter
and returns the corresponding offset. The example
below shows three months with the current one in the middle.
Since 4.0.0 - previously it was showCurrentAtPos .Since 4.0.6 - can be a function. |
monthsToStep | number | 1 | The number of months to move when the
previous or next
month commands are invoked. Since 4.0.0 - previously it was stepMonths . |
monthsToJump | number | 12 | The number of months to move when the
previous or next
year commands are invoked. Since 4.0.0 - previously it was stepBigMonths . |
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 4.0.3. |
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.Since 4.0.0 - previously it only affected the month drop-down with changeYear
controlling the year drop-down. |
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.
Since 3.7.3 - relative to today's year and combinations. Since 4.0.0 - 'any'. Since 4.0.3 - descending ranges. |
shortYearCutoff | string or number | '+10' | When a two-digit year format is used (see
dateFormat ),
this value helps determine the century for a given date.
If expressed as a number (0 to 99) it is the year beyond which
the century should be the last one instead of the current one.
If expressed as a string, it is converted to a number and added
to the current year before making the comparison above.
If set to -1 the year is always in the 1900s.Since 3.5.2 - disable with -1. |
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 .
Since 3.5.0. |
defaultDate | Date 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 (Date), 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.
Since 3.7.0 - added date string. |
selectDefaultDate | boolean | false | Set to true to automatically select the
defaultDate when no other date has been selected.
Since 4.0.0 - previously it was showDefault . |
minDate | Date or number or string | null | Specify the minimum date allowed to be selected.
This may be specified as an actual date (Date), 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.
Since 3.7.0 - added date string. |
maxDate | Date or number or string | null | Specify the maximum date allowed to be selected.
This may be specified as an actual date (Date), 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.
Since 3.7.0 - added date string. |
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.Since 3.7.1. |
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.Since 3.6.0. |
multiSeparator | string | ',' | Specify the separator shown between the dates selected in a
multiple date datepicker. Since 3.6.0. |
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 (Date, with time portion set to 12 noon),
along with a Boolean indicating whether the date is in the main month being shown
(as opposed to being an extra day before or after the main month),
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.
Since 4.0.0 - previously beforeShowDay provided similar functionality.Since 4.0.4 - time portion is 12 noon. |
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 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
datepick.ext module.
If you need multiple onShow callbacks, use the
multipleEvents
function and pass the relevant handlers to it.
Since 4.0.0. |
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.
|
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 (Date[]) as the parameter, while this refers to the associated control.
The array is empty if no dates have been selected.
All dates have their time portion set to 12 noon.
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.
Since 3.5.2 - added Date type parameter. Since 4.0.0 - dates parameter only.Since 4.0.4 - time portion is 12 noon. |
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 (Date[]) as the
parameter, while this refers to the associated control.
The array is empty if no dates have been selected.
All dates have their time portion set to 12 noon.
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.
Since 3.5.2 - added Date type parameter. Since 4.0.0 - dates parameter only.Since 4.0.4 - time portion is 12 noon. |
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.
|
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.
Since 4.0.0 - previously it was navigationAsDateFormat . |
commands | object | $.datepick. commands | See the
Commands tab for more details. Since 4.0.0. |