jQuery UI Datepicker

Defaults
Invocation
Keystrokes
Restricting
Formats
Customize
Localisation
Date range
Misc. 1
Misc. 2
Change Settings
Inline
Stylesheets
Compatibility

Defaults

A date picker can easily be added to an input field with default settings.

Default date picker: -

- -

IE select issue: -

The defaults are:

Date picker appears on focus
Text is in English
Date format is mm/dd/yyyy
Clear/Close controls show at the top
Month and year are selectable directly
10 years before and after the selected year are shown
Show a single month
Select a single date
Week starts on Sunday
Day names are clickable to change the first day of the week
Days in other months are not displayed
No date restrictions
Clicking elsewhere closes the date picker

Processed fields are marked with a class of hasDatepicker - and are not re-processed if targetted a second time.

You can override the default settings that apply to all date picker instances.

- -

Invocation

The date picker can be invoked in a variety of ways, as shown below. - Also shown is the use of an image only trigger, - and how the controls and buttons appear when disabled.

Datepicker appears on focus: - -

- -

Appears via text button: - -

- -

Appears both ways: - -

- -

You can embed the trigger image within the input area via CSS.

Embedded button: -

- -

Enable and disable datepicker with 'enable' and 'disable' commands.

- -

The date picker can also be triggered externally for a particular input.

External trigger: -

- -

Or even opened as a "dialog". If the blockUI plugin is available, - it is used to create a modal dialog.

Date picker dialog: - -

- -

Keystrokes

The date picker also responds to keystrokes entered in the input field.

Keyboard driven: -

The relevant keystrokes are:

page up/downprevious/next month
ctrl+page up/downprevious/next year
ctrl+homecurrent month or open when closed
ctrl+left/rightprevious/next day
ctrl+up/downprevious/next week
enteraccept the selected date
ctrl+endclose and erase the date
escapeclose the date picker without selection

Restricting

You can restrict the functionality of the date picker in various ways. - The first example sets the first day of the week to Monday and prevents it from being - changed, as well as preventing the month and year from being selected directly.

Restricted functionality: -

- -

You can also limit the range of dates selectable within the date picker. - Here it's between 26-Jan-05 and 26-Jan-07.

Limited dates: -

- -

Or set a range relative to today by specifying a number - rather than an exact date, in this case in the coming year.

Limited dates (relative): -

- -

The relative dates can also be specified as a number and a period - - 'd' for days, 'w' for weeks, 'm' for months, or 'y' for years.

Limited dates (extended): -

- -

Note that the range of selectable months and years changes appropriately. Also, - note that the Today link is no longer available as today is not in the range. - By default, the Prev and Next links are disabled if they are not - applicable. You can override this to remove them instead, with the - hideIfNoPrevNext setting.

Date Formats

You can set a variety of date formats for the date picker, - with the default being 'mm/dd/yy'.

Medium format: -

- -

Long format: -

- -

Full format: -

- -

Display dates without the century. The century is then determined based on the - shortYearCutoff setting, which defaults to 10 years in the future ('+10'). - Year values less than or equal to this cutoff are interpreted as being in the current - century, while those greater than the cutoff are taken to be in the previous century.

No century: -

- -

ISO date format: -

- -

French full format: -

- -

The formatting codes are:

dday of month (no leading zero)
ddday of month (two digit)
Dday name short
DDday name long
mmonth of year (no leading zero)
mmmonth of year (two digit)
Mmonth name short
MMmonth name long
yyear (two digit)
yyyear (four digit)
'...'literal text
''single quote

Customize

You can customize the selectability and/or appearance of individual days - by setting a callback function that accepts a date and returns an array - with the first entry being true/false for selectability and the second - entry being a CSS class to apply (or '' for none). One appropriate - function is built-in that prevents the selection of days on weekends.

No weekends: -

- -

Or you can provide your own function. The one below highlights and - prevents selection of a set of national days.

National days: -

- -

With CSS like the following:

.au_day { color: blue !important; background: #eee url(au.gif) no-repeat center !important; }

Localisation

You can localise the date picker for other languages and regional differences. - The date picker defaults to English with a date format of MM/DD/YYYY, - but you can easily translate the text into another language and date format.

- : -

The presentation is slightly different for right-to-left languages.

- : -

You need to load the appropriate language package, which - adds a language set ($.datepicker.regional[langCode]) and - automatically sets this language as the default for all date pickers.

<script type="text/javascript" src="ui.datepicker-fr.js"></script>

Thereafter, if desired, you can restore the original language settings.

$.datepicker.setDefaults($.datepicker.regional['']);

And then configure the language per date picker instance.

- -

Localisation packages:

Localisation packages can be found below under Settings and Documentation.

Date Range

Use a custom field settings function to create a date range control: - two date fields, each restricting the other. The function takes an - input field as an argument and returns a settings object (anonymous).

Date range: - to -

- -

Select a date range on one date picker, first click is the start date and second click is the end date. - The last example show six months in two rows of three months - with Previous and Next moving three months at a time.

Date range: -

- - -

Two months with range select: -

- -

Six months with range select: -

- -

Miscellaneous 1

Set the date shown when first opening the date picker. The default is today.

Open at 01-Jan-2007: -

- -

Open at 7 days from today: -

- -

Or specify a period from today - 'd' for days, - 'w' for weeks, 'm' for months, or 'y' for years. -

Open at 2 weeks from today: -

- -

Show the weeks of the year. Defaults to the ISO 8601 definition (weeks start - on Mondays and the first week of the year contains January 4). Change the - week calculation by setting calculateWeek to a function that - takes a date as a parameter and returns the number of the week.

Show week of the year: -

- -

Additional settings let you move the Clear/Close controls - to the bottom, hide the Clear control to make the date mandatory, - display the days in other months (non-selectable), - and show a status bar (with a custom display for today). - Callback functions are also added to operate when a date - is selected and when the datepicker is closed. - If no onSelect callback is specified, the - onchange event of the input field is triggered.

Additional settings: -

- -

Miscellaneous 2

Hide the datepicker on demand (press alt-h here) or - remove the datepicker altogether if you've finished with it.

Remove popup datepicker: - -

Remove inline datepicker: -

- -

(Advanced Technique)
Connect the date picker to linked drop-downs. You still need an input field, - but it is hidden following the drop-downs.

Linked drop-downs: - - - -

- -

Changing Settings

If necessary, the datepicker settings for an input (or set of inputs) - can be changed on the fly. As an example, here we change the - animation and speed at which the datepicker appears.

Display animation and speed: - - -

Change datepicker: -

When the option in the select changes, the following function is called:

- -

Date pickers can also be configured inline. - Add attributes to the input control with the namespace "date:" - corresponding to the date picker properties. - The attribute values are evaluated as JavaScript.

Inline configuration 1: - - blank

Inline configuration 2: -

- -

Inline

The date picker can be used inline rather than as a popup. - Use inline mode by attaching the datepicker to a span or div element.

- -

Show a number of months at once and set the range directly.

Inline range with two months:

- -

- Selected range is: - -

- -

(Advanced Technique)
- Set initial value of inline date range to one week before and after today's date. - Set the text field to current selected date.

- -

Stylesheets

The date picker can be formatted through the use of a stylesheet. - The default stylesheet is used in the rest of this demo - with an alternate one used here.

Alternate style: -

In a dialog: - -

The basic HTML structure of the date picker is shown below:

<div id="datepicker_div" class="datepicker_multi">
-  <div class="datepicker_control">
-    <div class="datepicker_clear"><a>Clear</a></div>
-    <div class="datepicker_close"><a>Close</a></div>
-  </div>
-  <div class="datepicker_links">
-    <div class="datepicker_prev"><a>&lt;Prev</a></div>
-    <div class="datepicker_current"><a>Today</a></div>
-    <div class="datepicker_next"><a>Next&gt;</a></div>
-  </div>
-  <div class="datepicker_oneMonth datepicker_newRow">
-    <div class="datepicker_header">
-      <select class="datepicker_newMonth"></select>
-      <select class="datepicker_newYear"></select>
-    </div>
-    <table class="datepicker" cellpadding="0" cellspacing="0">
-      <thead>
-        <tr class="datepicker_titleRow">
-          <td><a>Su</a></td><td><a>Mo</a></td>...
-        </tr>
-      </thead>
-      <tbody>
-        <tr class="datepicker_daysRow">
-          <td class="datepicker_daysCell datepicker_weekEndCell
-            datepicker_otherMonth datepicker_unselectable">31</td>
-          <td class="datepicker_daysCell"><a>1</a></td>
-          <td class="datepicker_daysCell datepicker_daysCellOver"><a>2</a></td>
-          <td class="datepicker_daysCell datepicker_daysCellOver datepicker_currentDay"><a>3</a></td>
-          <td class="datepicker_daysCell datepicker_today"><a>4</a></td>
-          ...
-        </tr>
-        ...
-      </tbody>
-    </table>
-  </div>
-  <div class="datepicker_oneMonth">
-    ...
-  </div>
-  <div style="clear: both;"></div>
-</div>

Compatibility

v3.3 to v3.4

The jQuery UI interfaces changed again, so here's another compatibility module.

Users of v3.3 of the datepicker should use the following - header code to work with their existing implementation:

<link rel="stylesheet" type="text/css" href="ui.datepicker.css"/>
-<script type="text/javascript" src="ui.datepicker.js"></script>
-<script type="text/javascript" src="ui.datepicker.compatibility-3.3.js"></script>

Download the ui.datepicker.compatibility-3.3.js module.

To migrate fully, the following steps need to be taken:

Replace references to the $(selector).attachDatepicker(...) - function with $(selector).datepicker(...).
Replace references to the $(selector).removeDatepicker() - function with $(selector).datepicker('destroy').
Replace references to the $(selector).datepicker.changDatepicker(...) - function with $(selector).datepicker('change', ...).
Replace references to the $(selector).datepicker.enableDatepicker() - function with $(selector).datepicker('enable').
Replace references to the $(selector).disableDatepicker() - function with $(selector).datepicker('disable').
Replace references to the $(selector).isDisabledDatepicker() - function with $(selector).datepicker('isDisabled').
Replace references to the $(selector).showDatepicker() - function with $(selector).datepicker('show').
Replace references to the $.datepicker.hideDatepicker() - function with $(selector).datepicker('hide').
Replace references to the $(selector).getDatepickerDate() - function with $(selector).datepicker('getDate').
Replace references to the $(selector).setDatepickerDate(...) - function with $(selector).datepicker('setDate', ...).

For example, this old style code:

$('inputs').attachDatepicker(...);
-$('inputs').changeDatepicker(...);

becomes:

$('inputs').datepicker(...);
-$('inputs').datepicker('change', ...);

- -

v3.2 to v3.4

To align the datepicker more closely with other jQuery UI components, - further changes were made in v3.3, resulting in another compatibility module.

Users of v3.2 of the datepicker should use the following - header code to work with their existing implementation:

<link rel="stylesheet" type="text/css" href="ui.datepicker.css"/>
-<script type="text/javascript" src="ui.datepicker.js"></script>
-<script type="text/javascript" src="ui.datepicker.compatibility-3.2.js"></script>

Download the ui.datepicker.compatibility-3.2.js module.

To migrate fully, the following steps need to be taken:

Replace references to the $.datepicker.reconfigureFor(selector, ...) - function with $(selector).datepicker('change', ...).
Replace references to the $.datepicker.enableFor(selector) - function with $(selector).datepicker('enable').
Replace references to the $.datepicker.disableFor(selector) - function with $(selector).datepicker('disable').
Replace references to the $.datepicker.isDisabled(selector) - function with $(selector).datepicker('isDisabled').
Replace references to the $.datepicker.showFor(selector) - function with $(selector).datepicker('show').
Replace references to the $.datepicker.getDateFor(selector) - function with $(selector).datepicker('getDate').
Replace references to the $.datepicker.setDateFor(selector, ...) - function with $(selector).datepicker('setDate', ...).

For example, this old style code:

$.datepicker.reconfigureFor('inputs', {...});

becomes:

$('inputs').datepicker('change', {...});

- -

v2.x to v3.3

The date picker has been refactored to better fit - within the jQuery UI project. - This has involved renaming the main function and some properties, - resulting in current uses of the plugin no longer functioning correctly. - To assist in the transition to the new format a compatibility - plugin is also provided, allowing current code to continue - to operate with minimal changes.

Existing users of v2 of the calendar should use the following - header code to work with their existing implementation:

<link rel="stylesheet" type="text/css" href="ui.datepicker.css"/>
-<script type="text/javascript" src="ui.datepicker.js"></script>
-<script type="text/javascript" src="jquery-calendar-compatibility.js"></script>

Download the jquery-calendar-compatibility.js module.

To migrate fully, the following steps need to be taken:

Replace references to the jquery-calendar* - files with ui.datepicker*.
Replace references to the popUpCal - object with $.datepicker.
Replace references to the calendar - function with datepicker.
Replace references to the autoPopUp - setting with showOn.
Replace references to the fieldSettings - setting with beforeShow.
Replace references to the customDate - setting with beforeShowDay.
Replace references to inline attributes with the cal: - namespace with date:.
Replace references to the hideCalendar - function with hideDatepicker.
Replace references to the dialogCalendar - function with dialogDatepicker.
Replace references to the $.datepicker.reconfigureFor(selector, ...) - function with $(selector).datepicker('change', ...).
Replace references to the $.datepicker.enableFor(selector) - function with $(selector).datepicker('enable').
Replace references to the $.datepicker.disableFor(selector) - function with $(selector).datepicker('disable').
Replace references to the $.datepicker.showFor(selector) - function with $(selector).datepicker('show').
Replace references to the $.datepicker.getDateFor(selector) - function with $(selector).datepicker('getDate').
Replace references to the $.datepicker.setDateFor(selector, ...) - function with $(selector).datepicker('setDate', ...).
Replace references to the calendar* - CSS styles with datepicker*.

For example, this old style code:

$('inputs').calendar({autoPopUp: 'both', fieldSettings: setDateRange,
-	customDate: popUpCal.noWeekends});
-	
-<input type="text" id="inlineConfig" cal:defaultDate="+7"/>

becomes:

$('inputs').datepicker({showOn: 'both', beforeShow: setDateRange,
-	beforeShowDay: $.datepicker.noWeekends});
-	
-<input type="text" id="inlineConfig" date:defaultDate="+7"/>

Localization Packages

- - - - - - - - - - - - - - \ No newline at end of file -- cgit v1.2.3