Child pages
  • Date Time Picker Specification

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 5.3


The current storycards are:

Wireframes & Storyboards

The current storyboards are:

Functional Requirements


Configurable Behaviors / Settings

Please note: These configuration options are also contained in the storycards, but are summarized here for ease of reading.

Allow all configurations on both a per application/site and per Date Time Picker basis:

  • Date Picker
    • Specify the date format displayed in the text box and "Today is:", either by implementer or user preferences. Default: Jan 1, 2009
    • Specify the format of the alternate presentation of the date above the text field. For example, if the date format in the text field is 2/11/09, above the text field "February 2nd, 2009" could be displayed.
    • Specify whether or not an alternate presentation of the date is displayed above the text field.
    • Specify non-selectable blackout dates (individual dates, ranges, holidays and all weekends).
    • Week's start day. Default: Sunday
    • Enable calendar to display right-to-left instead of left-to-right
    • Allow internationalization/localization by creating a mechanism to replace all text and numbers in the date picker with translations in other languages
    • Weekend days (which days of the week are considered "weekend" Default: Saturday and Sunday
    • Date picker format (whether one month is displayed at a time, two months at a time (either side by side or one underneath the other), or a 3x2 grid of 6 months at a time). Default: Single month display
    • Whether or not the calendar toggle icon is displayed inside the text field
    • Alignments for the date picker (e.g.
    • Whether there is just a time picker, just a date picker, or a date-time picker
    • Specify a maximum range (e.g. the current semester)
    • Specify the year range in the "Years" drop-down (e.g. the year options would likely be different for a birthday date picker, an assignment due date picker, and a museum's object acquisition date picker)
    • Whether or not "Today is:" is displayed
    • Whether the week #s are displayed.
    • Specify either a) when the weeks start (e.g. week 1 could be the first week in the semester) or b) that the week #s should be calculated using the ISO 8601 calendar system.
  • Time Picker
    • Specify default time format displayed in the text box, either by implementer or user preferences. Default: 11:55 pm
    • Whether to use a 12-hour or 24-hour clock
    • Whether or not a small clock toggle icon is displayed inside the text field
  • Date Time Picker
    • Whether a combined date-time field and a combined Date Time picker (as opposed to two separate pickers for date & time) is displayed
    • Whether or not the calendar toggle icon is displayed inside the text field

Internationalization & Localization

Localization: The process of converting a program to run in a particular locale or country, so that all text is displayed in the native language, and native conventions are used for sorting, formatting, etc.

Internationalization: The process of producing an application that can be localized for a particular country without any changes to the program code. Internationalized applications store their text in external resources, and use locale-sensitive utilities for formatting and collation.


  • We will target the gregorian calendar only
  • Allow the date, time, and time zone information to be localized across all of the date pickers in a certain context (s)
    Each Sakai user has the ability to set their own localization preferences for their UI, as well as each Sakai deployment setting an installation-wide default. The date widget should follow the correct algorithm for determining the appropriate Locale, and present the date and time information using
    • correctly localized Strings for month names (e.g. January, February) and days of the week (e.g. Monday, Tuesday)
    • correctly localized tool tips, error messages and directions (if there are any)
    • correctly localized start day of the week (e.g. Sunday or Monday)
    • correctly localized representation of an overall date, whether yy/mm/dd, yy/dd/mm etc.
    • correctly localized representation of hours, whether in a 12 hour clock with AM/PM or a 24-hour clock
    • detection of the timezone of the user (e.g. Sakai User Preference) and representation of time in database with the proper timezone, as well as representation of the proper time in the interface, keeping in mind the user's timezone
    • ability to detect the current date and time based on an appreciation of local timezones and cut-over days for daylight savings time, and display it properly in the interface when the current date or time is needed
    • allow for the text, calendar's week orientation (see and time picker to be displayed from right-to-left for languages which read right-to-left.
    • allow for the display of any day or days of the week as "weekends" (see
  • Potentially helpful documents:
  • Open question: is there a library (e.g. that we could use to do date recognition of different formats (e.g. 16 december, Dec 12, next Thursday) as well as smart population of the date time picker based on what is entered (e.g. user enters "J" the calendar goes to January, user enters "u" and calendar goes to June) that is internationalized? Or is there a way to provide this feature even if there isn't an internationalized library?

Potential Work with jQuery UI

It is possible we will work with jQuery UI to add the features and functionality (e.g. especially our Time Picker) in our specification and improve its accessibility rather than start from scratch with our own Date Time Picker. Their specification (which also represents ways we could extend our Date Time Picker in the future, e.g. additional config options) can be found here: jQuery UI Development & Planning Wiki: DatePickerCalendar and the Documentation page can be found here: UI/Datepicker/datepicker.