Getting Started

Requirements

  • jQuery 1.7.0 or above.
  • jQuery UI Core 1.8.6 or above.
    jQuery UI Core consists of the following components: Core, Widget, Mouse and Position. No other jQuery UI components are required.

Browser Support

Instead of targeting an ever increasing plethora of specific browsers we simply craft thoroughly designed, meticulously developed products using the latest standards, best practices and progressive enhancements. Our products work best with modern browsers, but will accommodate older browsers to the most practical extent possible.

Installation

Add ProDatePicker source files to your page:

<link rel="stylesheet" href="/prodatepicker-1.0.x/css/prodatepicker.css">
<script src="/prodatepicker-1.0.x/js/prodatepicker.js"></script>

ProDatePicker is now ready to use.

Usage

ProDatePicker can only be initialised on <input> elements of [type="text"] or [type="hidden"]. On initialisation the original source element is hidden and replaced with a read-only display <input>. The source <input> contains the value submitted to the server and the display <input> contains the value shown to the end user. This allows completely different date models to be used for data and display. See sourceModel and displayModel for more information.

Initialising ProDatePicker on an input with a readonly attribute automatically disables the widget.

To intialise a ProDatePicker widget with default options make an appropriate jQuery selection and call the proDatePicker() method.

$("#element").proDatePicker();

Options

altCalendar

Type: Boolean Default: false

Defines whether a simple date <select> list is displayed instead of a calendar layout. This alternative calendar is limited to displaying one month at a time, therefore setting altCalendar: true forces monthStep: 1. In some scenarios, particularly mobile, the smaller size and the native handling of <select> lists can improve the user experience.

$("#element").proDatePicker({
    altCalendar: true
});

calendarStep

Type: Number Default: null

Defines how many months the calendar moves forwards or backwards when the calendar navigation is triggered by an end user either clicking on calendar navigation buttons or mouse wheeling when over the calendar. Setting calendarStep: null sets the step equal to the number of months displayed.

$("#element").proDatePicker({
    calendarStep: 4 // The calendar moves forwards and backwards 4 months at a time
});

currentMonthAt

Type: Number Default: null

Defines the position of the calendar that contains the focused date when more than one month is displayed. The value must be between 1 and the number of months displayed inclusive. Setting currentMonthAt: null sets the position to be in the middle for an odd number of months and one place right of middle for an even number of months.

$("#element").proDatePicker({
    numberOfMonths: 3
    currentMonthAt: 3 // The calendar that contains the focused date is the third of three calendars displayed
});

debug

Type: Boolean Default: false

Setting debug: true enables debug logging in the console.

$("#element").proDatePicker({
    debug: true // Enable
});

defaultDate

Type: Array | Object | Number | String | Date | ProDate Default: null

Defines the date and time on which the calendar is focused when the widget is initialised without a selected date. If null the default date is the date and time the widget was initialised. The value is passed directly to the ProDate constructor, so any valid ProDate input value can be set.

$("#element").proDatePicker({
    defaultDate: [2014, 4, 9, 8, 16] // 9th April 2014 at 8.16am
});

disabled

Type: Boolean Default: false

Defines if the widget is able to accept interaction from the end user. Setting disabled: true disables the widget and all its controls. When disabled the widget can still be accessed using the API.

$("#element").proDatePicker({
    disabled: true // Disable
});

disableWeekends

Type: Boolean Default: false

Defines if the weekend days (Saturday and Sunday) are disabled in the date picker. Setting disableWeekends: true prevents end users from selecting weekend days. Weekend days can still be selected using the API with constraining disabled.

$("#element").proDatePicker({
    disableWeekends: true // Prevent Saturdays and Sundays from being selected by the end user 
});

displayModel

Type: String Default: null

Defines how the selected date is displayed to the end user and also determines how the widget is configured. Setting displayModel: null sets the value equal to the value of sourceModel. The displayModel must use the format defined by the format option and is used by ProDate for parsing and printing dates.

When displayModel is set the value is parsed and the information is used to determine if the widget is configured as a date picker, a time picker or a date and time picker. If displayModel only contains date elements (year, month, day of month, day of year, week etc.) then the widget is configured as a date picker. If displayModel only contains time elements (hours, minutes, seconds, meridiem etc.) then the widget is configured as a time picker. If displayModel contains both date and time elements the widget is configured as a date and time picker. This automatic configuration prevents end users from being asked to select a date when dates are not displayed or a time when time is not displayed.

// Date only widget configuration
$("#element").proDatePicker({
    format: "proDate", // Default format
    displayModel: "dddd, D MMMM YYYY" // e.g. Thursday, 19 March 2015
});

format

Type: String Default: "ProDate"

Defines the format used for parsing and printing dates and times. A format defines the elements that can be used in string models. The ProDate library is used by ProDatePicker for all date functions and its tokeniser can be configured to use any set of format elements. There are three pre-loaded formats:

ProDate
The default format using elements from the Moment.js JavaScript library.
PHP
A format using elements from the PHP date format.
Oracle
A format using elements from the Oracle Datetime format.

Format / Element ProDate PHP Oracle
Date D j DD1
Date Padded DD d DD1,3
Day Name dddd l DAY2
Day Name Short ddd D DY2
Day Name Min dd - -
Month M n MM1
Month Padded MM m MM1,3
Month Name MMMM F MONTH2
Month Name Short MMM M MON2
Year YYYY Y YYYY1
Day of Year DDD z DDD1
Day of Year Padded DDDD doyDDD1,3
Meridiem Lower a a am, pm, a.m., p.m.
Meridiem Upper A A AM, PM, A.M., P.M.
Hour 12 h g HH, HH121
Hour 12 Padded hh h HH, HH121,3
Hour H G HH241
Hour Padded HH H HH241,3
Minute m - MI1
Minute Padded mm i MI1,3
Second s - SS1
Second Padded ss s SS1,3
Decisecond S - FF11
Centisecond SS - FF21
Millisecond SSS - FF, FF31
Epoch X U -
Timezone Colon Z P -
Timezone ZZ O -
Timezone Hours - - TZH1
Timezone Minutes - - TZM1
ISO Week Year GGGG o IYYY1
ISO Week W W IW1
ISO Day of Week E N D1
Day of Week e w -
Quarter Q - Q1
Radix Point - - X1
Toggle Padding - - FM1
Toggle Strict - - FX1

Notes

  1. Numeric elements are case insensitive.
  2. String elements are case sensitive (the element case will be matched by the output.
  3. Padding is controlled by the FM (Fill Mode) modifier.
$("#element").proDatePicker({
    format: "PHP" // Uses PHP datetime format elements
});

locale

Type: String Default: null

Defines the language used for the widget UI, month and day names in dates and other country-specific date and time preferences. The value must be a language code that uses the same syntax used by the HTTP Accept-Language header: ISO 639-1 language code optionally followed by a hyphen separated ISO 3166-1 alpha-2 country code, e.g. en-gb English (United Kingdom), es-ar Spanish (Argentina), fi Finnish etc.

If a comma separated list of values is set then each value is tried in order and the first value that matches an available locale is used. If the value contains a country code in addition to a language code an exact match is sought first and if no match is found the language code is tried without the country code. If a value is set that does not correspond to any available locales then the generic English locale is used.

Setting null enables automatic language detection using the browser's preferred languages setting, i.e. the value of window.navigator.languages or equivalent.

$("#element").proDatePicker({
    locale: "en-GB, en" // Prefer British English if loaded else fallback to generic English
});

maxDate

Type: Array | Object | Number | String | Date | Selector | ProDate Default: null

Defines the latest selectable date and time. If null then there is no limit to the latest selectable date and time.

By setting maxDate to be another ProDatePicker using a jQuery selector the latest selectable date and time is the selected date of the target widget. If no date is selected in the target widget then there is no limit to the latest selectable date. Furthermore, ProDatePicker ensures that this link is created regardless of the initialisation order of widgets and dynamically updates the maximum date whenever the selected date of the target widget is changed. This feature enables easy pairing of ProDatePicker widgets to create dynamic date range pickers.

// Maximum date and time: 14th August 2018 at 3.45PM
// Array
$("#element").proDatePicker({
    maxDate: [2018, 8, 14, 15, 45] // ProDate arrays use month numbers 1-12!
});
// Object
$("#element").proDatePicker({
    maxDate: {year: 2018, month: 8, date: 14, hour: 15: minute 45}
});
// Number
$("#element").proDatePicker({
    maxDate: 1534257900000 // In local time
});
// String
$("#element").proDatePicker({
    sourceModel: "YYYY-MM-DDTHH:mm",
    maxDate: "2018-08-14T15:45"
});
// Date
$("#element").proDatePicker({
    maxDate: new Date(2018, 7, 14, 15, 45)
});
// Selector
$("#element").proDatePicker({
    maxDate: "#min-date" // Assumes ProDatePicker with ID "min-date"
});
// ProDate
$("#element").proDatePicker({
    maxDate: proDate([2018, 8, 14, 15]).add(45, "minutes") // All ProDate setters return ProDate
});

minDate

Type: Array | Object | Number | String | Date | Selector | ProDate Default: null

Defines the earliest selectable date and time. If null then there is no limit to the earliest selectable date and time.

By setting minDate to be another ProDatePicker using a jQuery selector the earliest selectable date and time is the selected date of the target widget. If no date is selected in the target widget then there is no limit to the earliest selectable date. Furthermore, ProDatePicker ensures that this link is created regardless of the initialisation order of widgets and dynamically updates the minimum date whenever the selected date of the target widget is changed. This feature enables easy pairing of ProDatePicker widgets to create dynamic date range pickers.

// Minimum date and time: 3rd April 2007 at 9.19AM
// Array
$("#element").proDatePicker({
    minDate: [2007, 4, 3, 9, 19] // ProDate arrays use month numbers 1-12!
});
// Object
$("#element").proDatePicker({
    minDate: {year: 2007, month: 4, date: 3, hour: 9: minute 19}
});
// Number
$("#element").proDatePicker({
    minDate: 1175588340000 // In local time
});
// String
$("#element").proDatePicker({
    sourceModel: "YYYY-MM-DDTHH:mm",
    minDate: "2007-04-03T09:19"
});
// Date
$("#element").proDatePicker({
    minDate: new Date(2007, 3, 3, 9, 19)
});
// Selector
$("#element").proDatePicker({
    minDate: "#max-date" // Assumes ProDatePicker with ID "min-date"
});
// ProDate
$("#element").proDatePicker({
    minDate: proDate([2007, 4, 3, 9]).add(19, "minutes") // All ProDate setters return ProDate
});

timeStep

Type: Number Default: 1

Defines the precision to which time is kept. The focused and selected dates are rounded down to the nearest number of minutes defined by timeStep. Additionally, the values displayed in the minute <select> element are limited to multiples of timeStep.

$("#element").proDatePicker({
    timeStep: 5 // Set time precision to 5 minutes
});
// Set selected date
$("#element").proDatePicker("selectedDate", [2012, 5, 3, 15, 27, 3]);
// Get display value
$("#element").proDatePicker("displayValue"); // "2012-05-03T15:25:00+0100"

monthAfterYear

Type: Boolean Default: false

Defines whether the month <select> element or name is displayed after the year <select> element or number. The result is achieved by manipulating the widget HTML (as opposed to using CSS).

$("#element").proDatePicker({
    monthAfterYear: true // Month displays after year in calendar navigation
});

numberOfMonths

Type: Number | Array<Number> Default: 1

Defines the number of month calendars to display in the date picker. The maximum number of calendars that can be displayed at once is 12. By default multiple calendars are displayed horizontally. For greater control over the layout of multiple calendars use an array to specify the number of rows and columns. Displaying more than one calendar forces showOtherMonths: false for a better user experience.

// Number
$("#element").proDatePicker({
    numberOfMonths: 5 // Display 5 months
});
// Array
$("#element").proDatePicker({
    numberOfMonths: [2, 3] // Display 6 months in 2 rows of 3 columns
});

padCalendar

Type: Boolean Default: false

Defines whether to force each calendar to display six rows regardless of the number of weeks in the month, thereby normalising the height of the calendar and preventing the height of the widget from changing as the calendar is updated. This is particularly useful when type: inline or numberOfMonths is greater than one.

$("#element").proDatePicker({
    padCalendar: true
});

placeholder

Type: String Default: null

Defines the placeholder text displayed in the display element and/or the widget header. If type: inline or type: modal a header is used in the widget to display placeholder text when no date is selected. If type: popup or type: modal a display <input> element is also used.

When a string is set the value will be used as the placeholder text. When placeholder: null the [placeholder] attribute of the source element is used if it exists and if it doesn't one of the following localised strings will be used depending on the widget configuration:

  • Select a date and time
  • Select a date
  • Select a time
The placeholder text is applied to the display <input> element using the HTML5 [placeholder] attribute. This attribute is not supported by all browsers, in particular IE <10.
// String
$("#element").proDatePicker({
    placeholder: "Date of birth" // Custom placeholder
});
$("#element").proDatePicker({
    placeholder: "" // No placeholder
});
// null
$("#element").proDatePicker({
    placeholder: null // source element placeholder attribute value or default string
});

rtl

Type: Boolean Default: null

Defines if the widget should be configured for right-to-left reading languages. In RTL mode the [dir] attributes of some widget elements are set to rtl. This triggers right-to-left rendering mode in most browsers and the positioning of the popup is also adjusted when type: popup. When set to null the direction is inferred from the css direction property of the widget element which in most cases results in the desired behaviour. However, this option can be used to explicitly set a direction if needed.

$("#element").proDatePicker({
    rtl: true // Enable RTL mode
});

selectedDate

Type: Array | Object | Number | String | Date | ProDate Default: null

Defines the selected date. On widget initialisation, if the source <input> element contains a value, that value will override this option. Dates selected with this option are never constrained. To select a constrained date use the selectedDate() method.

When using the option() method as a getter the value returned for this option is the value as last set, not the currently selected date. To get the currently selected date use the selectedDate() method.
// Selected date and time: 9th June 2015 at 7.02AM
// Array
$("#element").proDatePicker({
    selectedDate: [2015, 6, 9, 7, 2] // ProDate arrays use month numbers 1-12!
});
// Object
$("#element").proDatePicker({
    selectedDate: {year: 2015, month: 6, date: 9, hour: 7: minute 2}
});
// Number
$("#element").proDatePicker({
    selectedDate: 1433829720000 // In local time
});
// String
$("#element").proDatePicker({
    sourceModel: "YYYY-MM-DDTHH:mm",
    selectedDate: "2015-06-09T07:02"
});
// Date
$("#element").proDatePicker({
    selectedDate: new Date(2015, 5, 9, 7, 2)
});
// ProDate
$("#element").proDatePicker({
    selectedDate: proDate([2015, 6, 9, 7]).add(2, "minutes") // All ProDate setters return ProDate
});

selectMonth

Type: Boolean Default: true

Defines if the month is selectable in the widget UI. If selectMonth: true the month names are displayed in a <select> list in the date picker navigation. When the end user selects a month the calendar is updated to display the new focused date. If selectMonth: false the focused month name is displayed as text and the end user must use the mouse wheel, navigation buttons or keyboard to change the month.

$("#element").proDatePicker({
    selectMonth: false
});

selectOtherMonths

Type: Boolean Default: true

Defines if days in other months, if displayed, are selectable in the widget UI. When a single calendar is displayed, by default the otherwise empty table cells before the start and after the end of the focused month are filled with days from the end of the preceding month and the start of the following month. When selectOtherMonths: true these other days are selectable by the end user.

This option is only relevant when showOtherMonths: true and the number of months displayed is one.
$("#element").proDatePicker({
    selectOtherMonths: false
});

selectYear

Type: Boolean Default: true

Defines if the year is selectable in the widget UI. If selectYear: true the years defined by yearRange are displayed in a <select> list in the date picker navigation. When the end user selects a year the calendar is updated to display the new focused date. If selectYear: false the focused year is displayed as text and the end user must use the mouse wheel, navigation buttons or keyboard to change the year.

$("#element").proDatePicker({
    selectYear: false
});

showOtherMonths

Type: Boolean Default: true

Defines if the otherwise empty table cells before the start and after the end of the focused month are filled with days from the end of the preceding month and the start of the following month. This option only applies when the number of months displayed is one and altCalendar: false.

$("#element").proDatePicker({
    showOtherMonths: false
});

showWeek

Type: Boolean Default: false

Defines if ISO week numbers are displayed in month calendars. If altCalendar: true the days of the month are grouped by week.

Because ISO week numbers are based on the first day of the week being Monday then showWeek: true forces weekStart: 1.
$("#element").proDatePicker({
    showWeek: true
});

theme

Type: String Default: "silvercore"

Defines the theme class applied to the widget, display <input> and modal overlay. The theme class is the string "prodatepicker-theme-value". For this option to have any effect, related CSS styles that make use of the theme class must be present. Setting the widget theme using this option enables multiple themes to be loaded at once and applied to individual ProDatePicker instances independently of each other, or even for themes to be switched after initialisation.

$("#element").proDatePicker({
    theme: "my-theme" // Creates a class of "prodatepicker-theme-my-theme"
});

sourceModel

Type: String Default: "ISO_DATETIME"
A format "model" is a string literal that uses predefined format elements as placeholders for data. Whenever a string is parsed to a date, or a date printed to a string, a format model is used to map data from the input to the output.

Defines the format model that applies to the source element and all dates passed into the widget as strings. The value must use the format defined by the format option. The default value "ISO_DATETIME" is a preset format model defined by all formats which for the default format corresponds to "YYYY-MM-DDTHH:mm:ssZZ". The sourceModel is used for the following purposes:

  • Parsing the value of the source <input> element on initialisation.
  • Parsing the value of defaultDate, minDate, maxDate and selectedDate when the value is a string.
  • Printing the selected date to the source element.
$("#element").proDatePicker({
    format: "ProDate", // Default format
    sourceModel: "dddd, D MMMM YYYY" // e.g. Thursday, 19 March 2015
});

sourceZone

Type: Number | String Default: ""

Defines the time zone used to parse and output dates in the following situations:

  • Parsing the value of the source <input> element on initialisation.
  • Parsing the value of defaultDate, minDate, maxDate and selectedDate when the value is a string.
  • Outputting the selected date to the source element.
sourceZone only applies when parsing date strings that do not contain a time zone offset. Date strings with a time zone offset will always be parsed with that offset.

When working with dates from multiple end user time zones it is often useful to store dates in UTC (or some other fixed time zone) on the server and to display dates to end users in their local time. The sourceZone option accomplishes this.

The value null represents UTC when used as a time zone offset. To unset sourceZone use an empty string.
The values "Z" and null represent UTC when used as a time zone offset. When outputting, all time zone format elements will output "Z" for UTC dates. If the time zone offset "+00:00", "+0000" or "+00" is required use a sourceZone of "+00:00", "+0000" or 0 instead.
// String
$("#element").proDatePicker({
    sourceZone: "+05:00" // Time zone offset with colon
});
$("#element").proDatePicker({
    sourceZone: "+0300" // Time zone offset without colon
});
$("#element").proDatePicker({
    sourceZone: "-02" // Time zone offset without minutes
});
$("#element").proDatePicker({
    sourceZone: "Z" // UTC (printed with "Z")
});
$("#element").proDatePicker({
    sourceZone: "+0000" // GMT (printed with "+0000")
});
// Number
$("#element").proDatePicker({
    sourceZone: 300 // Offset minutes equivalent to "+05:00"
});
$("#element").proDatePicker({
    sourceZone: 180 // Offset minutes equivalent to "+03:00"
});
$("#element").proDatePicker({
    sourceZone: -120 // Offset minutes equivalent to "-02:00"
});
$("#element").proDatePicker({
    sourceZone: null // UTC (printed with "Z")
});
$("#element").proDatePicker({
    sourceZone: "" // Local
});

strict

Type: Boolean Default: false

Defines if date strings should be parsed in strict mode. If strict: true ProDate will use strict parsing mode.

$("#element").proDatePicker({
    strict: true // Enable strict date parsing
});

timeRange

Type: Function Default: null

Defines a callback function that can return start and end times for any given date. The function receives a ProDate and must return Array<String>. Strings must use the format "hh:mm". The first string represents the earliest selectable time and the second string represents the latest selectable time on the given day. If the value returned from the function is not an array with two elements, or if either of the strings cannot be parsed, the default start and end times are "00:00" and "23:59" respectively.

End times are necessarily inclusive otherwise it would be impossible to set a value that represents the end of the day ("23:59"). Since "00:00" represents the start of the given day it cannot also represent the start of the following day.
$("#element").proDatePicker({
    // timeRange callback is passed a ProDate
    timeRange: function (date) {
        // Call ProDate.dayOfWeek() to determine the day of the week and return the relevant start and end times
        switch (date.dayOfWeek()) {
            case 0: return ["01:00", "01:59"];
            case 1: return ["04:00", "04:59"];
            case 2: return ["07:00", "07:59"];
            case 3: return ["10:00", "10:59"];
            case 4: return ["13:00", "13:59"];
            case 5: return ["16:00", "16:59"];
            case 6: return; // Defaults to ["00:00", "23:59"]
        }
    }
});

type

Type: String Default: "popup"

Defines the display mode of the widget.

  • "inline" – the widget is inserted into the page immediately after the page item.
  • "modal" – the widget is initially hidden and opens with a background overlay when the display <input> element receives focus.
  • "popup" – the widget is initially hidden and opens as a drop down when the display <input> element receives focus.
$("#element").proDatePicker({
    type: "popup" // Default
});
$("#element").proDatePicker({
    type: "inline"
});
$("#element").proDatePicker({
    type: "modal"
});

utc

Type: Boolean Default: false

Defines if UTC mode is enabled. By default ProDatePicker operates in local mode which means dates are displayed in the end user's local time. This provides the best user experience since people are naturally used to working with dates in their local time. In some applications it can be useful for end users to see dates displayed in UTC. In local mode the same input date will result in different display dates for end users in different time zones. In UTC mode all end users, regardless of time zone, see the exact same date but will need to think in UTC when selecting dates and times.

UTC mode is not a good choice for most applications. If you are working with dates normalised to UTC on a server but still need end users to see dates in their local time you should almost always use the sourceZone option with a value of "Z" or null.

$("#element").proDatePicker({
    utc: true // Enable UTC mode
});

weekStart

Type: Number Default: 1

Defines on which day the week starts when displaying calendars, with the default being Monday. The days of the week are numbered from 1 (Monday) to 7 (Sunday) according to the ISO standard and from 0 (Sunday) to 6 (Saturday) according to the JavaScript standard. Both numbering systems are supported, so Sunday can be represented by either 0 or 7. All other days are numbered the same in both standards.

Setting showWeeks: true will force weekStart: 1, as week numbers are calculated using the ISO standard which uses Monday as the first day of the week.
$("#element").proDatePicker({
    weekStart: 5 // Friday
});

yearRange

Type: String Default: "focus-10:focus+10"

Defines the range of years displayed in the year <select> list. This option has no bearing on minimum and maximum selectable dates and only limits the number of year options available for performance and usability reasons.

The value must use a specific syntax in order to be parsed correctly. The format consists of a start year and an end year separated by a colon. Start and end years can be defined as either absolute or relative values:

Absolute years
Any 4 digit year
Relative years
An optional number of years, from -999 to 999 inclusive, to offset from one of the following base years:
  • "default" The default year defined by the defaultDate option.
  • "today" Today's year.
  • "focus" The focused date's year.
If the focused year falls outside the defined year range the year range will be extended to create a contiguous range of years that starts or ends with the focused year, so that the widget UI is always able to accurately display the focused date.
$("#element").proDatePicker({
    yearRange: "focus-10:focus+10" // A rolling 21 year range from 10 years before to 10 years after the focused date's year
});
$("#element").proDatePicker({
    yearRange: "1990:2020" // A 31 year fixed range
});
$("#element").proDatePicker({
    yearRange: "today:2030" // A relative to absolute range from today's year to 2030
});

zIndex

Type: Number Default: null

Defines the zIndex value applied to the widget with an inline style attribute. The zIndex controls the stacking order of positioned elements on the page. If your type: popup or type: modal widget is completely or partially blocked by another element the zIndex needs to be increased. Setting zIndex: null omits the inline zIndex style which means the CSS z-index value is used instead. The ProDatePicker CSS sets a z-index value of 100000 for the modal overlay and 100001 for popup and modal widgets. These values can be overridden with a custom theme or other CSS.

$("#element").proDatePicker({
    zIndex: 101
});
$("#element").proDatePicker({
    zIndex: null // Use CSS value
});

Methods

Widget methods are invoked by passing the method name to the jQuery plugin:

$("#element").proDatePicker("enable")

If a method accepts arguments they can be passed after the method name:

$("#element").proDatePicker("value", 10)

Most methods return the jQuery object for chaining:

$("#element").proDatePicker("enable").show()

However, some methods might return a value:

var value = $("#element").proDatePicker("value") // 10

clear()

Clears the selected date and returns focus to the defaultDate.

Arguments

This method does not accept any arguments

Return

Type: jQuery
The widget element for chaining.

$("#element").proDatePicker("clear")

close()

Closes the widget if type: popup or type: modal.

Arguments

This method does not accept any arguments

Return

Type: jQuery
The widget element for chaining.

$("#element").proDatePicker("close")

destroy()

Destroys the widget along with all associated data, elements and bindings. Restores the widget element to its pre-widget state.

Arguments

This method does not accept any arguments

Return

Type: jQuery
The widget element for chaining.

$("#element").proDatePicker("destroy")

disable()

Disables the widget UI completely. The only interaction to remain enabled when the widget is disabled is the end user's ability to close a type: popup or type: modal widget with the close button or by clicking outside the widget.

Arguments

This method does not accept any arguments

Return

Type: jQuery
The widget element for chaining.

$("#element").proDatePicker("disable")

displayElement()

Gets the generated <input> element used to display dates to the end user.

Arguments

This method does not accept any arguments

Return

Type: jQuery
The display <input> element.

$("#element").proDatePicker("displayElement")

displayValue()

Gets the string value displayed in the generated <input> element.

Arguments

This method does not accept any arguments

Return

Type: String
The date or text displayed to the end user.

$("#element").proDatePicker("displayValue") // "2015-04-16T15:32:00+0100"

enable()

Enables the widget UI completely.

Arguments

This method does not accept any arguments

Return

Type: jQuery
The widget element for chaining.

$("#element").proDatePicker("enable")

focusedDate()

Gets the focused date. The focused date is the date on which the widget is focused when no date is selected or when a date is selected but the calendar has been refocused. The focused date is always valid.

Arguments

This method does not accept any arguments

Return

Type: ProDate
The focused date.

var focusedDate = $("#element").proDatePicker("focusedDate");
focusedDate.toString() // "2018-12-01T15:23:59-0700"

focusedDate(input)

See also: focusedDate()

Sets the focused date. The focused date is the date on which the widget is focused. Setting the focused date has no effect on the selected date.

Arguments

input
Type: Array | Object | Number | String | Date | ProDate
A date as any valid ProDate input. If input can't be parsed or is otherwise an invalid date the focused date will be the selected date, if available, or the defaultDate.

Return

Type: jQuery
The widget element for chaining.

$("#element").proDatePicker("focusedDate", [2012, 5, 4, 21, 5])) // Focuses the widget on 4 May 2012 at 9.05 PM

open([position])

Opens the widget if type: popup or type: modal. Optional position properties can be passed to override the default positioning. The override position only applies to the method call for which it is passed. Subsequent calls to open() without an argument will use the default position.

Arguments

position
Type: Object
jQuery UI .position() properties. This argument can be used to override the default positioning of the widget. Properties passed by this argument will be merged into the default positioning properties1. Available properties and values depend on the version of jQuery UI.

Return

Type: jQuery
The widget element for chaining.

Notes

  1. The default position depends on the type and rtl options:
    type: popup + rtl: false
    {
        my: "left top",
        at: "left bottom",
        of: displayElement,
        collision: "none"
    }
    type: popup + rtl: true
    {
        my: "right top",
        at: "right bottom",
        of: displayElement,
        collision: "none"
    }
    type: modal
    {
        my: "center",
        at: "center",
        of: window,
        collision: "none"
    }
// Open the widget with default positioning
$("#element").proDatePicker("open");
// Open a popup widget above the displayElement
$("#element").proDatePicker("open", {
    my: "left bottom",
    at: "left top" 
})

option()

Gets the values of all options.

Arguments

This method does not accept any arguments

Return

Type: Object
An object containing all option values.

$("#element").proDatePicker("option")

option(optionName)

Gets the value of a single option.

Arguments

optionName
Type: String
The option to get.

Return

Type: Any
The option value. The type depends on the option.

$("#element").proDatePicker("option", "enabled")

option(options)

Sets multiple options.

Arguments

options
Type: Object
A map of option-value pairs.

Return

Type: jQuery
The widget element for chaining.

$("#element").proDatePicker("option", {
    disabled: true
})

option(optionName, value)

Sets a single option.

Arguments

optionName
Type: String
The option to set.
value
Type: Any
The value to set. The type depends on the option.

Return

Type: jQuery
The widget element for chaining.

$("#element").proDatePicker("option", "disabled", true)

selectedDate()

Gets the selected date.

Arguments

This method does not accept any arguments

Return

Type: ProDate
The selected date. If no date is selected an invalidated ProDate will be returned. This is different from an invalid ProDate and can be checked with the ProDate.isInvalidated() method.

var selectedDate = $("#element").proDatePicker("selectedDate");
selectedDate.toString() // "2018-12-01T15:23:59-0700"

selectedDate(input [, constrain])

See also: selectedDate()

Sets the selected date. By default the selected date is constrained based on the minDate, maxDate and timeRange options.

Arguments

input
Type: Array | Object | Number | String | Date | ProDate
A date as any valid ProDate input.
constrain
Type: Boolean
If false the selected date is not constrained.

Return

Type: jQuery
The widget element for chaining.

// Set the selected date
$("#element").proDatePicker("selectedDate", [2012, 5, 4, 21, 5])) // Selects 4 May 2012 at 9.05 PM
// Set the selected date, ignoring any constraints
$("#element").proDatePicker("selectedDate", new Date(1999, 4, 21, 4, 54), false))

setDate(year[, month[, dayOfMonth[, constrain]]])

Sets multiple date parts and optionally constrains the selected date. Omitted or null arguments are ignored so that the selected date part remains unchanged unless overflow values are set or other changes result in an invalid date, e.g. changing the year from a leap year to a standard year when the month is February and the date is 29 would result in the date changing to 28, or changing the month from July to June when the date is 31 would result in the date changing to 30.

Arguments

year
Type: Number
Sets the selected year or ignored if null.
month
Type: Number
Sets the selected month or ignored if null.
dayOfMonth
Type: Number
Sets the selected day of the month or ignored if null.
constrain
Type: Boolean
By default selected dates are constrained. Pass false to set an unconstrained date. If arguments are omitted the constrain argument can be passed last without needing to pass null values for the omitted arguments.

Return

Type: jQuery
The widget element for chaining.

// Set the selected year to 2005
$("#element").proDatePicker("setDate", 2005)
// Set the selected date to 23 April 2005 
$("#element").proDatePicker("setDate", 2005, 4, 23)
// Set the selected day of the month to the 1st 
$("#element").proDatePicker("setDate", null, null, 1)
// Set the selected date to 1999, ignoring minDate, maxDate and timeRange
// Since month and date arguments are omitted, the constrain argument can be passed as the last argument
$("#element").proDatePicker("setDate", 1999, false)

setNow()

Sets the selected time to "now" (the time at which this method is invoked). This method has no effect on the selected date. If no date is selected when this method is invoked the selected date will be be the focused date. If utc: true the time "now" will be the current time in UTC, which might not be the time "now" in the end user's local time.

Arguments

This method does not accept any arguments

Return

Type: jQuery
The widget element for chaining.

$("#element").proDatePicker("setNow")

setTime(hour[, minute[, second[, millisecond[, constrain]]]])

Sets multiple time parts and optionally constrains the selected date. Omitted or null arguments are ignored so that the selected time part remains unchanged unless overflow values are set.

Arguments

hour
Type: Number
Sets the selected hour or ignored if null.
minute
Type: Number
Sets the selected minute or ignored if null.
second
Type: Number
Sets the selected second or ignored if null.
millisecond
Type: Number
Sets the selected millisecond or ignored if null.
constrain
Type: Boolean
By default selected dates are constrained. Pass false to set an unconstrained date. If arguments are omitted the constrain argument can be passed last without needing to pass null values for the omitted arguments.

Return

Type: jQuery
The widget element for chaining.

// Set the selected hour to 15
$("#element").proDatePicker("setTime", 15)
// Set the selected timee to 07:32 
$("#element").proDatePicker("setDate", 7, 32)
// Set the selected minute to 58 
$("#element").proDatePicker("setDate", null, 58)
// Set the selected time to 22:03, ignoring minDate, maxDate and timeRange
// Since second and millisecond arguments are omitted, the constrain argument can be passed as the last argument
$("#element").proDatePicker("setDate", 22, 3, false)

setToday()

Sets the selected date to "today" (the date on which this method is invoked). This method has no effect on the selected time. If utc: true the date "today" will be the current date in UTC, which might not be the date "today" in the end user's local time.

Arguments

This method does not accept any arguments

Return

Type: jQuery
The widget element for chaining.

$("#element").proDatePicker("setToday")

sourceValue()

Gets the string value of the source <input> element.

Arguments

This method does not accept any arguments

Return

Type: String
The date or text submitted to the server.

$("#element").proDatePicker("sourceValue") // "2015-04-16T15:32:00+0100"

widget()

Gets the datepicker element.

Arguments

This method does not accept any arguments

Return

Type: jQuery
The datepicker element.

$("#element").proDatePicker("widget")

Events

Events can be handled by binding a function to the widget element using an event handler or by passing a function to the callback option on or after initialisation. Both methods can be used together on the same widget. When an event is triggered the bound event handlers are invoked before any callbacks are executed. Either method can be used to cancel a cancellable event, either by calling e.preventDefault() or returning false. If a handler and a callback are bound to the same event and the handler cancels the event the callback is still executed.

JQuery UI Widget Factory, on which ProDatePicker is built, provides inbuilt functionality to trigger widget events and when used this way generates event names automatically. However, these generated event names are different for different verions of jQuery UI and are slated to change again in the future:

widgetEventPrefix: The prefix prepended to the name of events fired from this widget. For example the widgetEventPrefix of the draggable widget is "drag", therefore when a draggable is created, the name of the event fired is "dragcreate". By default the widgetEventPrefix of a widget is its name. Note: This property is deprecated and will be removed in a later release. Event names will be changed to widgetName:eventName (e.g. "draggable:create").Widget Factory | jQuery UI API Documentation

In order to create a more stable widget, regardless of the version of jQuery UI Widget Factory running, ProDatePicker always triggers events with names using the format widgetname:eventname (lowercase). Therefore, you should always use the event names as documented, not the event name you might expect to use based on the version of jQuery UI running.

created(event, data)

Type: "prodatepicker:created" Cancellable: no

Triggered after the widget has been created.

Arguments

event
Type: Event
A jQuery Event object.
data.selectedDate
Type: ProDate
A clone of the selected date. Mutating the date in the event handler will have no effect on the selected date in the widget. If no date is selected this argument is an invalidated ProDate. Invalidated dates can be checked with the ProDate.isInvalidated() method.
data.focusedDate
Type: ProDate
A clone of the focused date. Mutating the date in the event handler will have no effect on the focused date in the widget. The focused date is always valid.
// Basic event handler
$("#element").on("prodatepicker:created", function (event, selectedDate) {
    console.log(event.type, selectedDate.toString()); // prodatepicker:created 2005-04-19T15:32:00+01:00
});
// Checking if a date is selected and valid
$("#element").on("prodatepicker:created", function (event, selectedDate) {
    if (selectedDate.isInvalidated()) console.log("No date is selected");
    else if (selectedDate.isValid()) console.log(selectedDate.toString()); // 2005-04-19T15:32:00+01:00
    else console.log(selectedDate.toString()); // Invalid date (date could not be resolved from input)
});
// Because the "created" event is triggered as soon as the widget is created, handlers must be bound _before_ the widget is initialised
$("#element").proDatePicker({
    // Basic event callback
    created: function (event, selectedDate) {
        console.log(event.type, "Callback", selectedDate.toString()); // prodatepicker:created 2005-04-19T15:32:00+01:00
    }
});

focused(event, data)

Type: "prodatepicker:focused" Cancellable: no

Triggered after a date is focused.

Arguments

event
Type: Event
A jQuery Event object.
data.selectedDate
Type: ProDate
A clone of the selected date. Mutating the date in the event handler will have no effect on the selected date in the widget. If no date is selected this argument is an invalidated ProDate. Invalidated dates can be checked with the ProDate.isInvalidated() method.
data.focusedDate
Type: ProDate
A clone of the focused date. Mutating the date in the event handler will have no effect on the focused date in the widget. The focused date is always valid.
$("#element").proDatePicker({
    // Basic event callback
    focused: function (event, focusedDate) {
        console.log(event.type, focusedDate.toString()); // prodatepicker:selected 2005-04-19T15:32:00+01:00
    }
});
// Basic event handler
$("#element").on("prodatepicker:focused", function (event, focusedDate) {
    console.log(event.type, focusedDate.toString()); // prodatepicker:selected 2005-04-19T15:32:00+01:00
});

selected(event, data)

Type: "prodatepicker:selected" Cancellable: no

Triggered after a date is selected.

Arguments

event
Type: Event
A jQuery Event object.
data.selectedDate
Type: ProDate
A clone of the selected date. Mutating the date in the event handler will have no effect on the selected date in the widget. If no date is selected this argument is an invalidated ProDate. Invalidated dates can be checked with the ProDate.isInvalidated() method.
data.focusedDate
Type: ProDate
A clone of the focused date. Mutating the date in the event handler will have no effect on the focused date in the widget. The focused date is always valid.
$("#element").proDatePicker({
    // Basic event callback
    selected: function (event, selectedDate) {
        console.log(event.type, selectedDate.toString()); // prodatepicker:selected 2005-04-19T15:32:00+01:00
    }
});
// Basic event handler
$("#element").on("prodatepicker:selected", function (event, selectedDate) {
    console.log(event.type, selectedDate.toString()); // prodatepicker:selected 2005-04-19T15:32:00+01:00
});
// Checking if a date is selected and valid
$("#element").on("prodatepicker:selected", function (event, selectedDate) {
    if (selectedDate.isInvalidated()) console.log("No date is selected");
    else if (selectedDate.isValid()) console.log(selectedDate.toString()); // 2005-04-19T15:32:00+01:00
    else console.log(selectedDate.toString()); // "Invalid date" (date could not be parsed from input)
});

User Interface

In addition to the expected mouse and touch interaction ProDatePicker has full keyboard support and mouse wheel controls.

Keyboard

Widget

When the widget is open, or is inline and has focus:

KeyAction
tSet the selected date to today
nSet the selected time to now
-Set an earlier time by subtracting the timeStep
+Set a later time by adding the timeStep
Page UpRefocus the calendar on an earlier date by subtracting calendarStep
Page DownRefocus the calendar on a later date by adding calendarStep
TabMove the focus to the next focusable element
Shift + TabMove the focus to the previous focusable element
DeleteClear the selected date
EscapeClose the widget (if applicable)

Calendar

When the calendar has focus:

KeyAction
Enter or SpaceSet the selected date to the focused date
Move the focused date back one day
Move the focused date forward one day
Move the focused date back one week
Move the focused date forward one week

Display Element

When the display element has focus but the widget is not open:

KeyAction
Enter or SpaceOpen the widget
tSet the selected date to today
nSet the selected time to now
DeleteClear the selected date

Mouse Wheel

When the widget is type: popup or type: modal mouse wheel control is enabled. When the widget is type: inline mouse wheel control is disabled to prevent unintended user interaction, e.g. when mouse wheel scrolling the page and the pointer moves over a widget.

Date Picker

When mouse wheeling over any part of the date picker:

DirectionAction
UpRefocus the calendar on an earlier date by subtracting calendarStep
DownRefocus the calendar on a later date by adding calendarStep

Time Picker

When mouse wheeling over any part of the time picker:

DirectionAction
UpSet an earlier time by subtracting the timeStep
DownSet a later time by adding the timeStep