jQuery-Mobile-DateBox

DateBox is a jQuery-mobile based date and time picker.

This is based in part on the work of Todd M. Horst, and his Android Like Date Picker 2

DateBox Features

• Multiple Data-Entry Modes:

  • Android style date picker
  • Calendar style date picker
  • Slide style date picker
  • 12 and 24 hour time picker
  • Duration time picker

• 4 Different display modes:

  • Standard, click-outside-to-close popup mode
  • Forced input modal popup mode
  • Unique page dialog mode
  • Inline mode

• Fully localized:

  • Configurable Month names
  • Configurable Day Names
  • All labels and buttons configuratble

• Supports data-limiting of input:

  • Configurable maximum and minimum years (android mode)
  • Configurable maximum and minimum number of days from "today" (both date modes)
  • Allows blacklisting of days of the week or specific dates (calendar mode)
  • Allows selecting specific day from any week selection (calendar mode)

• Automatically parses hand-entered or pre-entered dates on open

• Auto-bind's to data-type='datebox', options are configurable via data-options.

Suggested Use

// BEFORE loading jQM
$( document ).bind( "mobileinit", function(){
	$.mobile.page.prototype.options.degradeInputs.date = 'text';
});

No Option Overrides:

<input type="date" data-role="datebox" name="somedate" />

With Option Overrides:

<input type="date" data-role="datebox" name="somedate" data-options='{"buttonTheme": "b", "dateFormat": "mm/dd/YYYY"}' />

Global Option Overrides:

// AFTER loading jQM
jQuery.extend(jQuery.mobile.datebox.prototype.options, {
	'dateFormat': 'dd.mm.yyyy',
	'headerFormat': 'dd.mm.yyyy'
});

Available Options

These can be passed to datebox via an object set at the data-options attribute, or in the standard method.

• (operation mode) option : Description (default value)

Themeing:

• (all) theme : Theme for original input element. (c)
• (all) pickPageTheme : Theme for popup window or dialog. (b)
• (all) pickPageButtonTheme : Widget buttons. (a)
• (all) zindex : Z-Index for popup window. (500)
• (all) noAnimation : Disable popup window animations. (false)
• (all) centerWindow : Center the popup window in the viewport, rather than over the input element. (false)
• (android) pickPageInputTheme : Month/Date/Year Input Elements. (e)
• (slide) pickPageSlideButtonTheme : Non-centered slide buttons. (d)
• (cal/slide) pickPageHighButtonTheme : "Selected" Day highlighting. (e)
• (calendar) pickPageTodayButtonTheme : "Today" Day highlighting. (e)
• (calendar) pickPageOHighButtonTheme : highDates Date highlighting. (e)
• (calendar) pickPageODHighButtonTheme : highDays Date highlighting. (e)
• (calendar) calWeekModeHighlight : Toggle all buttons on week mode. (true)
• (calendar) disabledDayColor : Text color for disabled days with date limiting. (#888)
• (calendar) calHighToday : Boolean, use theme highlight for calendar "today". (true)
• (calendar) calHighPicked : Boolean, use theme highlight for calendar "picked date". (true)

Date Formats and Text Internationalization

• (android) daysOfWeek : An array of the days of the week. (['Sunday', 'Monday', ... 'Saturday'])
• (android) fieldsOrder : Define the order of the fields. (['m', 'd', 'y'])
• (cal/slide) daysOfWeekShort : An Array of abreviations for days of the week. (['Su', 'Mo', ... 'Sa'])
• (slide) monthsOfYearShort : An Array of abbreviations for the months. (['Jan', 'Feb', ... 'Dec'])
• (duration) durationOrder : Define the order of the fields. (['d', 'h', 'i', 's'])
• (duration) durationLabel : An Array of the parts of the duration. ('Days', 'Hours', 'Minutes', 'Seconds')
• (duration) durationDays : An Array of the singular and plural name for days. ('Day', 'Days')
• (duration) durationShort : Use the shortest mode possible to display duration. (true)
• (duration) durationNoDays : Do not break off days from duration, only h:i:s. (false)
• (duration) durationSteppers : An object of the amount to step each part of the duration. ({'d':1, 'h':1, 'i':1, 's':1})
• (all date) monthsOfYear : An Array of months of the year. (['January', 'February', ... 'December'])
• (all date) headerFormat : Return header format. (ddd, mmm dd, YYYY)
  • YYYY : 4 Digit Year
  • MM : 2 Digit Month (zero pad)
  • mm : 1 or 2 Digit Month
  • mmm : Text Month
  • DD : 2 Digit Day (zero pad)
  • dd : 1 or 2 Digit Day
  • ddd : Day of week
  • SS : Ordinal Suffix (4th, 3rd, 1st, etc)
  • NOTE experimentalReg must be enabled for ordinals.
• (both date) dateFormat : Return date format. (YYYY-MM-DD)
  • YYYY : 4 Digit Year
  • MM : 2 Digit Month (zero pad)
  • mm : 1 or 2 Digit Month
  • mmm : Text Month
  • DD : 2 Digit Day (zero pad)
  • dd : 1 or 2 Digit Day
  • ddd : Day of week
  • SS : Ordinal Suffix (4th, 3rd, 1st, etc)
  • NOTE experimentalReg must be enabled for ordinals.
• (time) timeFormat : Either '12' or '24' - The clock mode, 12hr or 24hr. (24)
• (time) meridiemLetters : Meridiem notation (['AM', 'PM'])

Data Limits:

• (all date) defaultDate : Default date when nothing entered into input box, array of [y,m,d] prefered, ISO accepted. (null)
  • NOTE ISO date is parsed due to iPad/iPhone limitation, it is (slightly) slower than the array method.
• (all date) afterToday : Limit date to "today" or after. (false)
• (all date) beforeToday : Limit date to "today" or before. (false)
• (calendar) notToday : Limit date to NOT "today". (false)
• (all date) maxDays : Set the upper limit to this # of days after today. (false)
• (all date) minDays : Set the lower limit to this # of days before today. (false)
• (android) maxYear : Maximum year allowed in controls (non-constrained in text box). (false)
• (android) minYear : Minimum year allowed in controls (non-constrained in text box). (false)
• (calendar) calWeekMode : Boolean, week mode on or off (choose only a specific DAY). (false)
• (calendar) calWeekModeFirstDay : Day of week to choose with week mode (numeric, 0-6, relative to calendar display). (1)
• (calendar) calStartDay : Day of week to start calendar on (numeric - 0=Sun, 1=Mon,... 6=Sat). (0)
• (calendar) blackDays : An array of days of the week to blacklist. (false)
  • example : [0,2] : Blacklist sunday and tuesday.
• (calendar) blackDates : A simple array of individual dates to blacklist. (false)
  • example : [ '2010-12-24', '2010-12-25' ] : Blacklist December 24th & 25th, 2010.
• (calendar) highDays : An array of days of the week to highlight. (false)
  • example : [0,2] : Highlight sunday and tuesday.
• (calendar) highDates : A simple array of individual dates to highlight with pickPageOHighTheme. (false)
  • example : [ '2010-12-24', '2010-12-25' ] : Blacklist December 24th & 25th, 2010.
• (time) minuteStep : Number of minutes to step per button press in timebox mode. (1)

User Interface:

• mode : Mode of operation. (datebox)
  • datebox : Android Style Datepicker
  • calbox : Calendar Datepicker
  • timebox : Android Style Time Picker
  • slidebox : Slide Style Datepicker
  • durationbox: Duration Style Time Picker
• (all date) experimentalReg : Use the new experimantal regex input parser. Please test! (false)
• (all) useDialogForceTrue : Boolean Always use Dialog Window, regardless of screen size. (false)
• (all) useDialogForceFalse : Boolean Never use Dialog Window, regardless of screen size. (false)
• (all) useModal : Use modal styling (background fades out) on popup. (false)
• (all) noButtonFocusMode : Suppress button, open on element focus instead. (false)
• (all) noButton : Suppress button. (false)
• (all) noSetButton : Do not show the set button. Probably only useful for inline mode. (false)
• (all) useInline : Show datebox inline on page, no dialog or popup. (false)
• (all) useInlineHideInput : When using inline mode, do not show the input box. (false)
• (all) titleDialogLabel: Dialog label override. (false)
• (all) closeCallback : A function to run on DateBox close. (false)
• (all) swipeEnabled : Swipe gestures active (only cal / slide for now). (true)
• (android) setDateButtonLabel : The label displayed in the set date button. (Set Date)
• (calendar) calShowDays : Boolean show day names in grid. (true)
• (calendar) calShowOnlyMonth : show only this month, do not fill in empty boxes. (false)
• (duration) setDurationButtonLabel : The label displayed in the set duration button. (Set Duration)
• (all date) titleDateDialogLabel: Dialog label for date mode. (Set Date)
• (time) setTimeButtonLabel : The label displayed in the set time button. (Set Time)
• (time) titleTimeDialogLabel: Dialog label for time mode. (Set Time)

To disable the element, use the standard disabled='disabled' in your markup.

Value Notes (durationbox) - Supported initial strings:

• seconds : 140
• minutes:seconds : 121:10
• hours:minutes:seconds : 34:12:10
• days string, hours:minutes:seconds : 3 ignored, 03:12:10

Runtime Operation (Scripting / Extending)

Public Member Functions

The plugin supports a number of public functions:

• $('element').datebox('open'); // Open the DateBox control

• $('element').datebox('close'); // Close the DateBox control

• $('element').datebox('disable'); // Disable the DateBox control

• $('element').datebox('enable'); // Enable the DateBox control

• $('element').datebox('refresh'); // Force the DateBox control to refresh it's display (see below)

Callback events

jQM-Datebox supports a number of jQuery events. They all are triggered on:

$('element').bind('datebox', function (e, passed) { ... });

Where passed is an object conatining:

• method : Method triggered:

  • refresh : Triggerd on HTML / data refresh (very frequent)
  • open : Triggerd on DateBox open
  • close : Triggered on DateBox close
  • enable : Triggered on DateBox enable
  • disable : Triggered on DateBox disable
  • set : Triggered on setting a date (followed by close)
  • offset : Triggered on internal date change with:

• amount : (offset method) Amount to add to value (can be negative)

• type : (offset method) Value updated:

  • y : Year
  • m : Month
  • d : Date
  • h : Hour
  • i : Minute
  • s : Second
  • a : Meridian

Just-In-Time options updating

The following options can be changed after initialization (i.e. in per-page scripts after load). Almost all will require you to refresh the control.

• Data limiting:
  • minDays & maxDays & afterToday
  • minYear & maxYear
  • blackDays & blackDates
  • calWeekMode & calWeekModeFirstDay
  • minuteStep
• Display / Internationalization:
  • calStartDay
  • daysOfWeek, daysOfWeekShort, monthsOfYear, monthsOfYearShort, headerFormat
  • dateFormat (probably - it will throw off reopens though)
  • Dialog mode forcing (either on or off)
• Any of the calendar of slide mode themes (except the base theme) & disabledDayColor & calWeekModeHighLight
• closeCallback

The following options happen to early, and cannot be changed post-initialization by script events.

• Operation mode
• Any of the labels on buttons / window titles.
• Any of the themes on the datebox or time modes.
• Any of the options related to inline display
• noButtonFocusMode, useModal, zindex, noAnimation, timeFormat, fieldsOrder