Datepicker
A highly configurable plugin that adds datepicker functionality to your pages. You can restrict the functionality in various ways, you can select date ranges, and you can provide the date in picker in a number of languages.
Demo
Script Example
In this sample, a datepicker with the name of 'myDatepicker' is created with two initial properties. The function argument of createControl is called when the widget renders, and a date is set.
Create the control…
App.createControl( 'myDatePicker', 'jquery_datepicker', { }, function() { this.setDate(new Date(2009, 5, 24)); } );
Get the handle to an instance of the control, then enable it…
App.getControl('myDatePicker', 'jquery_datepicker', function() { this.enable(); });
Options
The datepicker control is made up of a single div. The control tag on the div indicates what kind of widget the div will become. The widget identity can accept the following initial parameters…
Initial options supported by the widget.
| Option | Description | Default | Type |
|---|---|---|---|
| clearText | The text to display for the clear link. This attribute is one of the regionalisation attributes. | Clear | String |
| clearStatus | The text to display in the status bar for the clear link. This attribute is one of the regionalisation attributes. | Erase the current date | String |
| mandatory | True if a date must be selected, causing the Clear link to be removed. False if the date is not required. | false | Bool |
| closeText | The text to display for the close link. This attribute is one of the regionalisation attributes. | Close | String |
| closeStatus | The text to display in the status bar for the close link. This attribute is one of the regionalisation attributes. | Close without change | String |
| closeAtTop | Position the Clear/Close links at the top (true) or bottom (false). | true | Bool |
| prevText | The text to display for the previous month link. This attribute is one of the regionalisation attributes. | <Prev | String |
| prevStatus | The text to display in the status bar for the previous month link. This attribute is one of the regionalisation attributes. | Show the previous month | String |
| nextText | The text to display for the next month link. This attribute is one of the regionalisation attributes. | Next> | String |
| nextStatus | The text to display in the status bar for the next month link. This attribute is one of the regionalisation attributes. | Show the next month | String |
| 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. | false | Bool |
| currentText | The text to display for the current day link. This attribute is one of the regionalisation attributes. | Today | String |
| currentStatus | The text to display in the status bar for the current day link. This attribute is one of the regionalisation attributes. | Show the current month | String |
| gotoCurrent | If true, the current day link moves to the currently selected date instead of today. | false | Bool |
| 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. | false | Bool |
| monthNames | The list of full 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. | ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'] | Array |
| monthNamesShort | The list of abbreviated month names, for use as requested via the dateFormat setting. This attribute is one of the regionalisation attributes. | ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'] | Array |
| changeMonth | Allows you to change the month by selecting from a drop-down list. You can disable this feature by setting the attribute to false. | true | Bool |
| monthStatus | The text to display in the status bar for the month drop-down list. This attribute is one of the regionalisation attributes. | Show a different month | String |
| yearRange | Control the range of years displayed in the year drop-down: either relative to current year (-nn:+nn) or absolute (nnnn:nnnn). | -10:+10 | String |
| changeYear | Allows you to change the year by selecting from a drop-down list. You can disable this feature by setting the attribute to false. | true | Bool |
| yearStatus | The text to display in the status bar for the year drop-down list. This attribute is one of the regionalisation attributes. | Show a different year | String |
| weekHeader | The column header for the week of the year (see showWeeks). This attribute is one of the regionalisation attributes. | Wk | String |
| weekStatus | The text to display in the status bar for the week of the year. This attribute is one of the regionalisation attributes. | Week of the year | String |
| 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. | ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'] | Array |
| 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. | ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'] | Array |
| 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. | ['Su', 'Mo', 'Tu', 'We', 'Th', 'Fr', 'Sa'] | Array |
| firstDay | Set the first day of the week: Sunday is 0, Monday is 1, … This attribute is one of the regionalisation attributes. | 0 | Int |
| changeFirstDay | Allows you to click on the day names to have the week start on that day. You can disable this feature by setting the attribute to false. | true | Bool |
| dayStatus | The text to display in the status bar for the day of the week links. Use 'DD' for the full name of the day, or 'D' for its short name. This attribute is one of the regionalisation attributes. | Set DD as first week day | String |
| highlightWeek | If true, the entire week row is highlighted when the mouse hovers over a day. | false | Bool |
| showOtherMonths | Display dates in other months (non-selectable) at the start or end of the current month. | false | Bool |
| dateStatus | The text to display in the status bar for the date links. Use any of the date formatting characters (see dateFormat). This attribute is one of the regionalisation attributes. | Select DD, M d | String |
| showWeeks | Display the week of the year alongside each month. The column header is specified by the weekHeader setting. The week number is calculated based on the first date shown in each row in the datepicker, and so may not apply to all days in that row. The calculateWeek setting allows you to change the week of the year calculation from the default ISO 8601 implementation. | false | Bool |
| calculateWeek | Perform the week of the year calculation. This function accepts a Date as a parameter and returns the number of the corresponding week of the year. The default implementation uses the ISO 8601 definition of a week: weeks start on a Monday and the first week of the year contains January 4. This means that up to three days from the previous year may be included in the first week of the current year, and that up to three days from the current year may be included in the last week of the previous year.” | String | |
| 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. | 1 | Int |
| stepMonths | Set how many months to move when clicking the Previous/Next links. | 1 | Int |
| rangeSelect | Set to true to allow the selection of a date range on the one date picker, or false to just select a single date. For a date range, the first click sets the start date and a second click sets the end date. | false | Bool |
| rangeSeparator | Set the text to use to separate the two dates in a date range via the onSelect function. | - | String |
| defaultDate | Set the date to display on first opening if the field is blank. Specify either an actual date via a Date object, or relative to today with a number (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. | null | String |
| minDate | Set a minimum selectable date via a Date object, or relative to today with a number (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. | null | String |
| maxDate | Set a maximum selectable date via a Date object, or relative to today with a number (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. | null | String |
| 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. | null | String |
| 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. | +10 | String |
| initStatus | The text to display in the status bar when the datepicker is first opened. This attribute is one of the regionalisation attributes. | Select a date | String |
| showStatus | True if a status bar should be shown within the datepicker indicating what each control does. False if no status bar is required. | false | Bool |
| statusForDate | The function to call to determine the status text for a date within the datepicker. The default function uses the dateStatus value and substitutes in information from the current date. | null | String |
| appendText | The text to display after each date field, e.g. to show the required format. | null | String |
| duration | Control the speed at which the datepicker appears, it may be a time in milliseconds, a string representing one of the three predefined speeds ('slow', 'normal', 'fast'), or ' ' for immediately. | normal | String |
| 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'). | focus | String |
| showAnim | Set the name of the animation used to show/hide the datepicker. Use 'show' (the default), 'slideDown', 'fadeIn', or any of the show/hide jQuery UI effects. | show | String |
| showOptions | If using one of the jQuery UI effects for showAnim, you can provide additional settings for that animation via this option. | {} | Object |
| buttonText | The text to display on the trigger button. Use in conjunction with showOn equal to 'button' or 'both'. | … | String |
| buttonImage | The URL for the popup button image. If set, button text becomes the alt value and is not directly displayed. | null | String |
| buttonImageOnly | Set to true to place an image after the field to use as the trigger without it appearing on a button. | false | Bool |
| beforeShow | Can be a function that takes an input field and current datepicker instance and returns a settings (anonymous) object to update the date picker with. It is called just before the datepicker is displayed. | null | Function |
| 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 and [1] equal to a CSS class name(s) or '' for the default presentation. It is called for each day in the datepicker before is it displayed. | null | Function |
| altField | The jQuery selector for another field that is to be updated with the selected date from the datepicker. Use the altFormat setting below to change the format of the date within this field. Leave as blank for no alternate field. | null | String |
| altFormat | The dateFormat to be used for the altField above. This allows one date format to be shown to the user for selection purposes, while a different format is actually sent behind the scenes. | null | String |
| onSelect | Allows you to define your own event when the datepicker is selected. The function receives the selected date(s) as text and the datepicker instance as parameters. this refers to the associated input field. | null | Function |
| onChangeMonthYear | Allows you to define your own event when the datepicker moves to a new month and/or year. The function receives the date of the first day of the first displayed month and the datepicker instance as parameters. this refers to the associated input field. | null | Function |
| 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(s) as a date or array of dates and the datepicker instance as parameters. this refers to the associated input field. | null | Function |
| isRTL | True if the current language is drawn from right to left. This attribute is one of the regionalisation attributes. | false | Bool |
| constrainInput | True if the input field is constrained to the current date format. | true | Bool |
Actions/JavaScript API
Functions either accept a single argument such as an integer or a string, otherwise they accept a one dimensional object literal. Any function that can be called as an action accepts the same parameters but in the action parameter format. For example…
this.setDate(new Date(2009, 04, 02);
is equivalent to…
<div control="jquery_datepicker" id="myDatepicker" on="l:setMe then setDate[04/02/2009]"> </div>
| Function | Action | Description |
|---|---|---|
| enable() | enable | Enable the datepicker. |
| disable() | disable | Disable the datepicker. |
| isDisabled() | Returns the boolean value of the state of the datepicker. | |
| option() | option | Reoption the datepicker with any of the initial values. |
| hide() | hide | Hide the datepicker. |
| show() | show | Show the datepicker. |
| getDate() | Returns the current value of the datepicker. | |
| setDate(obj) | setDate[] | The function accepts an object literal with two members; “date” (date), and “endDate” (date). The action accepts the two parameters with the same names; the types can be strings and they will be parsed with javascript. |
