Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
A multi-mode date and time picker for jQueryMobile
JavaScript PHP Perl

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
build
css
demos
external
js
screens
tests
LICENSE
README.md
index.html

README.md

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
Something went wrong with that request. Please try again.