type: widget

release: 0.0

status: in planning

demo/documentation: http://jqueryui.com/demos/datepicker/

refactor branch demo: http://jquery-ui.googlecode.com/svn/branches/labs/datepicker/demos/index.html#datepicker|default

 

---

 

1 - Description:

 

This is a brand new planning page to discuss the code re-factor of the current datepicker plugin:

http://jqueryui.com/demos/datepicker/

 

To have a fresh start on the planning on this re-factor, the older wiki page that covered current and future datepicker and calendar ideas is archived here: DatePickerCalendar

 

The specific code and functionality changes we want to address in this refactor are:

• Add the ability to customize the buttons in the bottom button bar. This would allow users to add a "clear form" button, shortcuts like "today" or "next delivery date". This would be similar to the dialog widget. I'd imagine it would looks something like this:

  $('.selector').datepicker({

  buttons: {

  'clear': function(event, ui){

  $(this).val('');

  }

  }

  });

• Improve datepicker positioning/z-index issues in dialogs and overlays, especially in IE

• Re-factor the code to better match the jQuery UI API - a version is now available at http://github.com/kbwood/jquery-ui.

 

 

Sampling of feature requests that we might want to consider adding or accomodating as an extension to core picker:

 

• Show week numbers - worth including?

• Select multiple days on a calendar

• Select a range on a calendar

• Disable list of specific dates or days of the week

• Highlightlist of specific or days of the week (maybe with an optional custom class)

• Assign custom events to days (use case: inline datepicker with tooltips on days)

• Allow datepicker to show on hover or allow this to be customised in the showOn option to accept any event.

• Add time selection.

   

   

---

 

2 - Visual Design:

 

 

 

---

 

 

3 - Functional Specifications/Requirements:

 

Options:

• showOnFocus (Boolean, default: true)
• When true a popup datepicker appears when the input field gains focus, when false showTrigger should be used instead.
• showTrigger (string or element or jQuery, default: null)
• An external element that triggers a popup datepicker for an input field. It can be either a jQuery selector, an HTML fragment, the actual element, or a jQuery collection containing the element. The given element is cloned for each input field and is placed after/before the field depending on the prevailing language direction.
• showAnim (string, default: 'show')
• The name of the animation to use when opening/closing a popup datepicker. It can be one of the built-in animations ('show', 'fadeIn', 'slideDown') or any of the jQuery UI animations. Use '' for no animation, just an immediate show/hide. (Is there a better way of describing an animation as an object, rather than using this and the following options to control different bits of it?)
• showOptions (object, default: {})
• Any additional options for a jQuery UI animation, e.g. change 'clip' to run horizontally: {direction: 'horizontal'}.
• showSpeed (number or string, default: 'normal')
• The speed at which the opening/closing animation plays. It can be either the name of a standard speed ('slow', 'normal', 'fast') or the duration in milliseconds.
• popupContainer (string or element or jQuery, default: null)
• The container to which the popup datepicker is appended.It can be either a jQuery selector, the actual element, or a jQuery collection containing the element. If not specified 'body' is used. This allows the datepicker to be repositioned within the DOM to allow for custom handling or styling.
• myPosition (string, default: '')
• The position of the popup datepicker division relative to its input field (using position plugin values). If not specified 'left top' or 'right top' is used depending on the language direction.
• atPosition (string, default: '')
• The anchor point of the popup datepicker on its input field (using position plugin values). If not specified 'left bottom' or 'right bottom' is used depending on the language direction.
• fixedWeeks (Boolean, default: false)
• When true six weeks are always shown in the datepicker. When false only the actual number of weeks required for the current month are shown.  
• monthsToShow (number or number[2], default: 1)
• The number of months to show at the one time. It is either the number of columns, or the number of rows and columns (as an array).
• monthsOffset (number, default: 0)
• The offset from its normal position for the current month. For example, a value of 1 would place the current month in the second position and show the previous month in the first position.
• monthsToStep (number, default: 1)
• The number of months to move each time the previous/next month is requested.
• monthsToJump (number, default: 12)
• The number of months to move each time the previous/next year is requested.
• changeMonth (Boolean, default: false)
• When true the month and year can be changed directly via drop-down lists. When false the month and year are displayed only and changes must be made with the previous/next buttons.
• yearRange (string, default: 'c-10:c+10')
• The range of years to show in the year drop-down for user selection. It consists of the start and end values separated by a colon (:), with each value being one of '+/-nn' for an offset from today's year, 'c+/-nn' for an offset from the first currently selected date (or today if none), 'nnnn' for an absolute year. For example, '1980:-10' indicates a range from 1980 to 10 years before today. Use a special value of 'any' to allow direct entry of the year instead of selection from a drop-down. Note that this option only affects the year drop-down list and that minDate/maxDate must be used to restrict the range of dates that may be selected.
• shortYearCutoff (number or string, default: '+10')
• When the short year format is used, this option determines which century is applied to the date. If a number (0-99) is given it is used directly. If a string is given it is added to the current year within the century. Then any partial year greater than the derived value is deemed to be in the previous century. Use a value of -1 to disable this feature and always use 1900.
• showOtherMonths (Boolean, default: false)
• When true days from other months that precede or follow the current month are shown in the datepicker. When false these days do not appear.
• selectOtherMonths (Boolean, default: false)
• When true (and showOtherMonths is also true) the dates from other months that precede or follow the current month are able to be selected. When false these dates are display only.
• defaultDate (Date or string or number, default: null)
• The date to highlight when no other date has been selected in the datepicker. It is either an actual Date object, a string with the date in the current dateFormat, a number of days offset from today, or a string of units and periods offset from today - using 'y' for years, 'm' for months, 'w' for weeks, 'd' for days, e.g. '+1m -1d'. If not specified today is used.
• selectDefaultDate (Boolean, default: false)
• When true and no other date has been selected the defaultDate is automatically selected as the field value. 
• minDate (Date or string or number, default: null)
• The minimum date allowed to be selected in the datepicker. It is either an actual Date object, a string with the date in the current dateFormat, a number of days offset from today, or a string of units and periods offset from today - using 'y' for years, 'm' for months, 'w' for weeks, 'd' for days, e.g. '+1m -1d'. If not specified there is no minimum. 
• maxDate (Date or string or number, default: null)
• The maximum date allowed to be selected in the datepicker. It is either an actual Date object, a string with the date in the current dateFormat, a number of days offset from today, or a string of units and periods offset from today - using 'y' for years, 'm' for months, 'w' for weeks, 'd' for days, e.g. '+1m -1d'. If not specified there is no maximum.
• autoSize (Boolean, default: falsel)
• When true the input field is automatically resized to fit a date in the current dateFormat. When false the input field's size is unchanged.
• altField (string or element or jQuery, default: null)
• A reference to another field that is maintained in synch with the datepicker selections. It can be either a jQuery selector, the actual element, or a jQuery collection containing the element.
• altFormat (string, default: null)
• The dateFormat to apply to the altField. This allows the selected date to be shown in one format to the user while maintaining a second format more suited for internal processing.
• constrainInput (Boolean, default: true)
• When true keystrokes in the input field are constrained to those accepted by the dateFormat. When false any keystroke is accepted.

   

   

   

Localisation:

• monthNames (string[12], default: ['January', ...])
• The full names of the months.
• monthNamesShort (string[12], default: ['Jan', ...])
• The abbreviated names of the months.
• dayNames (string[7], default: ['Sunday', ...])
• The full names of the days of the week starting from Sunday.
• dayNamesShort (string[7], default: ['Sun', ...])
• The abbreviated names of the days of the week starting from Sunday.
• dayNamesMin (string[7], default: ['Su', ...])
• The minimal names of the days of the week starting from Sunday.
• firstDay (number, default: 0)
• The index of the first day of the week: 0 is Sunday, 1 is Monday, ...
• dateFormat (string, default: 'mm/dd/yyyy')
• The format for the date that appears in the input field. Use 'd' for day of the month, 'dd' for day of the month two digits, 'o' for day of the year, 'oo' for day of the year three digits, 'D' for day of the week abbreviated, 'DD' for day of the week full, 'm' for month, 'mm' for month two digits, 'M' for month name abbreviated, 'MM' for month name full, 'yy' for year two digits (see shortYearCutoff), 'yyyy' for year four digits, '@' for Unix timestamp, '!' for Windows ticks, other characters as literals. Quote (') reserved characters to prevent their substitution. 
• isRTL (Boolean, default: false)
• When true the language runs right-to-left. When false it runs left-to-right.

 

 

Methods:

• .datepicker('enable')
• Enable the datepicker field and any associated trigger.
• Returns the jQuery object.
• .datepicker('disable')
• Disable the datepicker field and any associated trigger.
• Returns the jQuery object.
• .datepicker('isDisabled')
• Determine whether or not a datepicker is disabled.
• Returns true if the first entry in the list has its datepicker disabled, false if not.
• .datepicker('getDate')
• Retrieve the currently selected date.
• Returns the selected date or null if none selected.
• .datepicker('setDate', date)
• Alter the currently selected date.
• date (Date) is the new selected date, or null to clear it.
• Returns the jQuery object.
• .datepicker('show')
• Popup the datepicker for an input field.
• Returns the jQuery object.
• .datepicker('hide')
• Hide the current popup datepicker.
• Returns the jQuery object.
• .datepicker('showMonth', year, month, [day])
• Set the datepicker to show the given year and month.
• year (number) is the new year to show.
• month (number) is the new month to show (1-12).
• day (number, optional) is the day within this month to highlight initially.
• Returns the jQuery object.
• .datepicker('changeMonth', offset)
• Move the datepicker to show a new month relative to the current one.
• offset (number) is the number of months to move.
• Returns the jQuery object.
• .datepicker('changeDay', offset)
• Move the cursor date by a number of days, showing a new month/year if necessary.
• offset (number) is the number of days to move.
• Returns the jQuery object.

 

 

Events:

• onDate
• Called for each date as it is added to the datepicker, allowing that date's appearance/behaviour to be customised.
• Accepts the date as a parameter.
• Returns an object with (all optional) attributes: selectable (Boolean) true if this date is selectable, false if not, dateClass (string) any CSS classes to apply to the date, title (string) popup tooltip for the date, content (string) customised content to replace the default day-of-the-month number.
• onShow
• Called after the datepicker has been constructed but before display, allowing the datepicker's appearance/behaviour to be customised.
• Accepts the datepicker div and current instance settings as parameters.
• May update the provided div.
• Returns nothing.
• changeMonthYear
• Called when the datepicker displays a new month/year, e.g. when previous/next buttons are clicked.
• Accepts the new date (first of the new month) as a parameter.
• Returns nothing.
• select
• Called when a date is selected or cleared.
• Accepts the new date (or null if cleared) as a parameter.
• Returns nothing.
• close
• Called when a popup datepicker is closed (with or without selection).
• Accepts the currently selected date (or null if none) as a parameter.
• Returns nothing.

 

 

---

 

4 - Markup & Style:

 

     4.1 Initial markup examples

 

<input type="text" name="myDatepicker">

 

<input type="date" name="myDatepicker" min="1970-01-01" max="2020-12-31" value="2009-05-22">

     4.2 Recommended transformed HTML markup

 

     (The HTML markup structure and classes that will be used by the scripts in the enhanced version) 

 

     4.3 Accessibility recommendation

 

    (Detailed recommendations for ARIA, HTML markup, CSS and javascript that will contribute to universal access and full section 508 accessibility for screen readers, mobile devices and any other devices) 

 

Issues with current datepicker:

• focus is indicated using color alone
• the next/prev month icons are invisble in high contrast mode, not indication of focused day is available.
• thecontrols/links in the date picker do not recieve programmtaic focus.
• table caption not explictly associated.
• Expansions for day abbreviations not provided

 

     4.4 CSS & Theme

 

    (Description of the CSS classes to be used for all states, how custom theming and Themeroller support will work.) 

 

---

 

5 - Latest version of plugin:

 

http://jquery-ui.googlecode.com/svn/trunk/demos/datepicker/index.html

 

Refactor to jQuery UI widget available at http://github.com/kbwood/jquery-ui.

 

---

 

6 - Open issues being discussed

 

• What's the best way to deal with backwards compatibility? Should this be built-in for now as deprecated code for removal in 1.next + 1? Or should we provide a compatibility script which means by default if a user upgrades their existing code will break unless they also add this compatility script.
• Should the datepicker support any DOM element?

 

---