Unobtrusive Date-Picker Widget Update

The LowDown

An attempt at writing a datePicker (calendar) that is accessible using the keyboard, requires no embedded JavaScript blocks, uses no pop-up windows and is suitable for use within documents served as application/xhtml+xml.

A quick feature list…

• Fully keyboard accessible
• Multiple date formats and date dividers supported
• Unobtrusive and nameSpace friendly
• Fully skinnable with CSS
• Both upper and lower date limits can be set
• Certain days of the week can be disabled
• Certain, dates can be disabled/enabled (and wildcards used to stipulate the dates in question)
• Includes “smart” localisation (16 languages currently available)
• Bespoke days of the week can be highlighted
• Works with single text inputs, split text inputs or select lists
• It’s free to use, even commercially (Released under a CC share-alike license)

Splitting the date across three text inputs

The datePicker can now work with dates that have been split across three text inputs (an input for the day, an input for the month and one for the year). Just add the class split-date to the associated year input’s className. Inputs that have the class split-date do not have to stipulate a date format.

In order for the script to be able to locate both the month and day inputs, the month input should be given the same ID as the year input with the string “-mm” added to the end and the day input should be given the same ID as the year input with the string “-dd” added to the end. All of the normal configuration classes should be added to the year input’s className only.

An example of splitting the date in this way is shown in the demo.

Splitting the date across three select lists

The datePicker can now work with dates that have been split across three individual select lists (one for the day, one for the month and one for the year). Just add the class split-date to the associated year select lists’s className. Select lists that have the class split-date do not have to stipulate a date format.

In order for the script to be able to locate both the month and day lists, the month select list should be given the same ID as the year select list with the string “-mm” added to the end and the day select list should be given the same ID as the year select list with the string “-dd” added to the end. All of the normal configuration classes should be added to the year select list ‘s className only.

Select lists and date ranges

As the year select list can only stipulate a finite number of years, the datePicker will automatically create a higher and lower date limit using the selectList data i.e. if the year select list starts at 1960 and ends at 1990, the associated datePicker will automatically disallow the selection of dates outside of this range.

Select lists and invalid dates

Should the user select an invalid date using the select lists e.g. 31st September (remember, September has only 30 days!), the datePicker will automatically show a corrected date of the 30th September when launched.

Date formats and the date divider

The date-picker currently supports dates of the format dd-mm-yyyy, mm-dd-yyyy, yyyy-mm-dd or yyyy-dd-mm. The date format is declared by adding one of the following classes to the associated input’s className; format-d-m-y, format-m-d-y or format-y-m-d. Inputs that do not have the class split-date have to have one of the aforementioned “format” classes as, without it, no datePicker is created.

Additionally, the character used to separate the date parts can be “/”, “-”, “.” or “ “ (space). Again, this is declared by adding one of the following classes to the associated inputs className attribute; divider-slash, divider-dash, divider-dot or divider-space.

Creating static datePickers

If you wish to have the datePicker always displayed on-screen i.e. with no activation button; just add the class no-fade to the associated input.

Highlighting days of the week

By default, Saturday and Sunday are highlighted in another colour (in a burgundy red for the demo). Should you wish other days of the week to be highlighted instead, add a class of the format highlight-days-N to the associated input’s class attribute where N represents is a numeric representation of the days you wish to highlight e.g. adding the class highlight-days-012 will highlight Monday (0), Tuesday (1) and Wednesday (2).

Localisation

The script attempts to auto-detect the language of the users browser installation and download the corresponding language file from the server. Should the language file not exist, the datePicker display defaults to English.

Currently available languages

The following languages are currently available:

• English
• Spanish
• French
• Portugese (thanks to Sérgio Jardim)
• German
• Dutch
• Greek (UTF-8: thanks to seloh)
• Finnish (thanks to Kalle Pyörälä of Primesoft)
• Romanian (UTF-8: thanks to Ionut Marinescu)
• Russian (UTF-8: thanks to Flack)
• Italian (thanks to Raf)
• Arabic (UTF-8: thanks to Hassan)
• Swedish (thanks to Henrik)
• Norwegian (thanks to Eirik)
• Ukranian (UTF-8: thanks to VojToshik)
• Hebrew (UTF-8: thanks to Yoav)

If your language of choice isn’t shown, you can easily create the file yourself by using the “en.js” file as a template; of course, I would appreciate a copy of the new language file to add to the distribution.

New language files are, due to Internet Explorers hazy handling of UTF-8 encoded JavaScript files, better off stipulated as unicode.

I’ve bundled an HTML file (unicode.html) with the download that enables you to translate entire UTF-8 phrases into their Unicode equivalents. This is based on the Slayer Office unicode lookup service – a URL every web developer should have bookmarked.

Should you wish to disable the detect locale functionality, add the class no-locale to the associated input’s className – the datePicker will then display in English, it’s default language.

Please Note: Version 3.6 introduced a “Today” button that has, at present, only been translated into French, English, Hebrew and Spanish. All other languages will display the button in English until the word “Today” has been translated and added to the respective language files.

The “first day of the week”

The first day of the week is now stipulated within the downloaded language file. Should the language file not contain this setting, the first day of the week defaults to Monday.

Additionally, users can now click on any of the day headers to dynamically set it as the first day of the week (or alternately, press the numbers 2-7 on the regular keyboard or numpad).

JavaScript access to the datePicker object

The individual datePicker JavaScript Objects can now be accessed by calling:

    
  datePickerController.datePickers["the associated input's id"]
    
  

This means that all of the inputs now require an ID attribute should you wish to access their associated datePicker Object.

Limiting date selection

The date-picker enables you to define both a lower and upper limit for date selection. Dates outside of the specified range are grayed out and unselectable.

To add a lower or upper limit, stipulate them as part of the associated inputs className e.g. adding range-low-2005-12-02 range-high-2005-12-20 to the className will limit the selection of dates to between the 2nd, December 2005 and the 20th, December 2005.

Date ranges declared in this way have to be constructed using a YYYY-MM-DD format.

Should you just wish to default either the upper or lower limits to today’s date, you can add either of the classes range-high-today or range-low-today.

Setting the date range dynamically

The upper and lower date ranges can be set programmatically by calling the following two methods:

    
  datePickerController.datePickers[“the associated input id”].setRangeLow(“YYYYMMDD date string”);

  datePickerController.datePickers[“the associated input id”].setRangeHigh(“YYYYMMDD date string”);
    
  

The dates passed to the two methods should be stipulated using the YYYYMMDD date format e.g. 20060230 (which can be constructed by calling the inbuilt “dateFormat” method as shown within the source code to the reservation date demo).

Be warned, the script does no validation checks on the date ranges when changed in this way i.e. it does not check if the higher date is actually higher than the lower date; so it’s up to you to validate the date ranges before calling the methods in question.

An example of using the setRangeHigh and setRangeLow methods can be viewed within the reservation date demo.

Disabling dynamically calculated dates

It is now possible to disable/enable dates that require a date calculation; for example, Easter. This requires you to add an “onupdate” method to the datePickerController Object. This method is called every time either the datePicker’s displayed month or year changes and is passed the datePicker JavaScript Object as an argument. An example of extending the datePickerController Object this way is shown below:

  
 // Calculate and disable Easter
 datePickerController.onupdate = function(dp) {
        // dp = the datePicker Object
        // dp.date = the datePickers Date Object

        var x = dp.date.getFullYear();
        var a=x%4;
        var b=x%7;
        var c=x%19;
        var d=(19*c+15)%30;
        var e=(2*a+4*b-d+34)%7;
        var f=Math.floor((d+e+114)/31);
        var g=(d+e+114)%31+1;

        var dt = datePickerController.dateFormat(x + “/” + f + “/” + g);
        // Disable Easter for this datePicker 
        dp.setDisabledDates([dt]);
 }
  
 

A working example of the above code (that also creates a dynamic style for the date in question) can be viewed within the onUpdate demo

Disabling day selection

You can now stipulate days of the week to disable. This is done by adding the class disable-days-N to the associated input’s className, where N is a string of integers that represents the days of the week you wish to disable; for example, adding the class disable-days-12 will disable Monday (1) and Tuesday (2) for the associated datePicker.

An example of disabling days in this way is shown in the demo.

Disabling day selection dyamically

Should you wish to disable the day selection programmatically, call the datePicker’s setDisabledDays method, passing in an array of seven binary numbers that represent which days of the week to disable; for example, passing the array [1,0,0,0,0,0,0] will disable Monday, passing [1,0,1,0,1,0,0] will disable Monday, Wednesday and Friday.

  
  // Disable Monday, Wednesday and Friday
  datePickerController.datePickers["the associated input id"].setDisabledDays([1,0,1,0,1,0,0]);
  
  

An example of disabling days of the week dynamically can be seen in the disable days demo.

Disabling date selection

You can now stipulate specific dates to disable. Unlike the other configuration options, this can only be achieved by calling the datePickers setDisabledDates method and not by adding a class to the associated input’s className.

Stipulating the dates to disable

The dates you wish to disable should be stipulated in a YYYYMMDD format and can contain wildcards for both the year and month; for example, passing the Array [“20061225”, “****1231”, “******01”] to the setDisabledDates method will disable the 25th of December 2006 (“20061225”), the 31st of December for all years (”****1231”) and the first day of every month for all years (”******01”).

  
  // Disable specific dates 
  datePickerController.datePickers["the associated input id"].setDisabledDates(["20061225", "****1231", "******01"]);
  
  

An example of disabling dates in this way can also be seen in the disable days demo.

Enabling only specific dates

You can now stipulate specific dates to enable, all other dates will be greyed out and unselectable. Like the setDisabledDates configuration option, this can only be achieved by calling the datePickers setEnabledDates method and not by adding a class to the associated input’s className.

Stipulating the dates to enable

The dates you wish to enable should be stipulated in a YYYYMMDD format and can contain wildcards for the year, month and date parts; for example, passing the Array [“200612**”, “****1131”, “******01”] to the setEnabledDates method will enable all dates within December 2006 (“200612**”), the 31st of November for all years (”****1131”) and the first day of every month for all years (”******01”).

  
  // Enable specific dates only
  datePickerController.datePickers["the associated input id"].setEnabledDates(["200612**", "****1231", "******01"]);
  
  

Disabling the transparency effects

To disable the fade-in/fade-out effect, just add the class no-transparency to the associated input.

Styling individual dates

To enable you to target and style individual dates using CSS, each TD node is now given two extra classNames of the format dm-date-month and dmy-date-month-year, where date is replaced by the integer date value, month is replaced by the integer month value and year replaced by the integer year value e.g. the TD node for the date 21/03/2007 will be given the classNames dm-21-3 and dmy-21-3-2007.

The active “cursor”

This version of the script has a much better system for showing the current “cursor” position.

A cursor is necessary as the datePicker is keyboard accessible and keyboard users require a visual clue as to which date is currently active i.e. which date will be selected when the carriage return key is pressed.

Currently, the datePicker shows the selected date with a black border and black text and the current cursour position in blue.

Keyboard accessibility

The arrow keys can be used to change the highlighted day. Pressing CTRL + ← or → increments/decrements the current month. Pressing CTRL + ↑ or ↓ increments/decrements the current year.

Keeping the keyboard or mouse button depressed activates a timed increment i.e. there’s no need to repeatedly press the mouse button or arrow keys.

Pressing Enter selects the currently highlighted date, pressing Esc closes the datePicker without selecting a date and Space highlights todays date. Additionally, pressing 2 to 7 (using the numpad or regular keyboard) now sets the associated day to be the “first day of the week”.

Bugs and foibles

Our good friend Internet Explorer requires (for reasons that I won’t detail here) that each input you wish to create a datePicker for, has a unique ID attribute assigned to it.

The License

The script is now released under a creative commons Attribution-ShareAlike 2.5 license. Should you use the script within a commercial context (or are feeling generous today), please think about clicking the payPal donate button – it’s certainly not an obligation but it would most certainly put a smile on my face.

Demo, downloads and updates

View the updated date-picker demo, the reservation date demo or download the .zip file of the of the datePicker JavaScript, CSS and accompanying images.

The JavaScript code can be “packed” using Dean Edwards Packer should size be an issue.

Additionally, a Rails plug-in has been developed by Brian Landau and is available from the google code repository. Thanks Brian!

22/01/2008 (v4.4):

• SelectLists can now contain default options e.g. “choose month” or optGroups
• Fixed a bug in IE when attempting to focus on a hidden text input
• Moved the button creation code into the datePicker Object

19/12/2007 (v4.3):

• Fixed a disableDates bug

15/11/2007 (v4.2):

• Fixed a Safari2 bug

05/11/2007 (v4.1):

• Rewrote the rendering code to be much faster than before
• Fixed a bug that enabled keyboard users to select disabled dates
• Added the “static” datePicker option (no-fade className)
• Changed the activation button to use an “A” element, not a “button” element

13/09/2007 (v4.0):

• Added a tabIndex to each TD element containing a date
• Added a call to the onupdate method of datePickerController (if it exists) which enables you to enable/disable holidays that have to be calculated e.g. Easter
• Tidied up the CSS and added a new background image for blank TD elements
• Fixed the keyboard control in Safari

03/08/2007 (v3.9):

• Changed the code that dynamically loads the locale file to enable the packed version to be used without having to rename it from datepicker_packed.js to datepicker.js
• Added the selectList functionality (thanks to Richard Davies for the friendly nudge)
• Changed the code to always download a locale file, even when the detected language is English
• Added a “Show Calendar” toolTip to the dynamically created button (currently only available within the French and English locales)

02/08/2007 (v3.8):

• Removed Internet Explorer’s dependance on the “blank.html” document
• Added a loosely packed version of the script to the download (rename it from datepicker_packed.js to datepicker.js when in use)

15/06/2007 (v3.7):

• Added the Hebrew language file (thanks to Yoav)
• Added the Internet Explorer BASE check (heads-up to Shaun Inman)

12/06/2007 (v3.6):

• Added the “Today” button
• Wrapped the Month name and Year within the title bar in spans to enable easier styling
• Fixed a once-in-a-blue-moon date calculation bug (many thanks to Ryan Rushton for the bug report and testcase)

17/04/2007 (v3.5):

• Fixed a bug that added incorrect classNames to each td node

03/04/2007 (v3.4):

• Fixed a bug in the range-high and range-low (today) parsing

27/03/2007 (v3.3):

• Fixed a positioning bug in Internet Explorer
• Fixed a bug that meant the html page “jumped” when a datePicker was activated for the first time

22/03/2007 (v3.2):

• Added the setEnabledDates method
• Fixed a bug within the setDisabledDates method

13/03/2007 (v3.1):

• Rewrote the setDateFromInput method to be more robust when invalid dates are encountered.
• Added the “range-high-today” and “range-low-today” options.

12/03/2007 (v3.0):

• Worked on Internet Explorer memory leaks.
• Added extra classNames to each TD node to enable styling of individual dates.

09/02/2007 (v2.9):

• Fixed a bug that appeared when the automatic “daylight savings” calculation was activated on a Windows machine (many thanks to Tony Calleri of IBM Global Services for locating and fixing the problem).

31/01/2007 (v2.8):

• Added functionality that disables the next/previous buttons when appropriate.

03/01/2007 (v2.7):

• Added functionality that enables you to switch off the transparency effects for individual datePickers.

14/12/2006 (v2.6):

• Fixed an Internet Explorer bug that meant the datePicker never disappeared.
• Added the setDisabledDates method.

12/12/2006 (v2.5):

• Changed the code to enable the script to be used in “quirksmode” scenarios.

01/12/2006 (v2.4):

• Fixed a bug that removed the button used to activate the datePicker after an Ajax call updated the associated input’s innerHTML

06/11/2006 (v2.3):

• Changed the dateFormat function to accept an extra Boolean parameter that, when TRUE, stipulates whether to attempt to parse a “m-d-y” formatted date before a “d-m-y” formatted date
• Changed the setRangeLow and setRangeHigh methods to accept a YYYYMMDD date format string
• Bundled the “reservation date” example with the .zip download
• Added the “setDisabledDays” method
• Fixed a “colspan” issue for Internet Explorer
• Added a fix that disables date selection when the datePicker is fading in or out of view
• Changed the datePicker to position itself in relation to the associated calendar icon and not the associated text input
• DatePickers that have the class “split-date” now do not need to stipulate a date format
• Added code that attempts to always reposition the datePicker within the bounds of the browser viewport

02/11/2006 (v2.2):

• Removed references to uppercase tagNames and lowercased the colSpan reference (thanks to Meryn for the info)

19/10/2006 (v2.1):

• Changed the license
• Integrated code that dynamically calculates the blank.html document’s location (which should always be placed within the same directory as the datepicker.js javascript file)
• Fixed the Internet Explorer “NaN” bug when an invalid date is entered into the input box (thanks to Jan Brašna for the fix)

  
  function init() {

    // A local function that creates a two character string
    function makeTwoChars(inStr) {
      return inStr < 10 ? "0" + inStr : inStr;  
    }

    // I’m assuming your input has the id "myInput"
    var myInput = document.getElementById("myInput");

    // Create a new date Object
    var dt = new Date();

    // I’m assuming the "date-format" is d-m-y 
    // and the "date-divider" a forward slash
    myInput.value =  makeTwoChars(dt.getDate()) + "/" + makeTwoChars(dt.getMonth()) + "/" + dt.getFullYear();
    
  }