jQuery Date/Time Entry Reference

A jQuery plugin that sets an input field up to accept a date and time value using a spinner. If you find this plugin useful please vote for it on the jQuery site.

This page provides a documentation reference for working with the plugin v1.0.1. See a demonstration of the date entry plugin and download the code from there.

Instance Settings

A separate date/time entry instance is created for each invocation of $(selector).datetimeEntry();. Each instance may have different settings for their input field(s), e.g.

$(selector).datetimeEntry({datetimeFormat: 'Y-O-D H:M'});

Alternately, you can specify the settings per control by including the jQuery Metadata plugin in your page and adding them to the class attribute, e.g.

<input type="text" class="{datetimeFormat: 'Y-O-D H:M'}"/>

Below are the settings that may be applied to each date/time entry instance. All are optional.

A note on Date - the JavaScript Date constructor expects the year, month, and day as parameters. However, the month ranges from 0 to 11. To make explicit what date is intended (does a month of 3 mean March or April?) I specify the month from 1 to 12 and manually subtract the 1. Thus the following denotes 25 December, 2010.

$(selector).datepick({minDate: new Date(2010, 12-1, 25)});

altField | altFormat | ampmNames | appendText | beforeShow | datetimeFormat | datetimeSeparators | dayNames | dayNamesShort | defaultDatetime | initialField | isRTL | maxDatetime | maxTime | minDatetime | minTime | monthNames | monthNamesShort | shortYearCutoff | spinnerBigImage | spinnerBigSize | spinnerImage | spinnerIncDecOnly | spinnerRepeat | spinnerSize | spinnerTexts | timeSteps | useMouseWheel

NameTypeDefaultComments
datetimeFormatstring'O/D/Y H:Ma' The format for the date/time display. Use the following characters for the fields:

  • 'y' - two-digit year
  • 'Y' - four-digit year
  • 'o' - month
  • 'O' - two-digit month
  • 'n' - abbreviated month name
  • 'N' - full month name
  • 'd' - day
  • 'D' - two-digit day
  • 'w' - abbreviated day name and number
  • 'W' - full day name and number
  • 'h' - hours
  • 'H' - two-digit hours
  • 'm' - minutes
  • 'M' - two-digit minutes
  • 's' - seconds
  • 'S' - two-digit seconds
  • 'a' - AM/PM indicator
If the AM/PM indicator is not present the time is assumed to be 24-hour. Other characters are the separator(s) allowed between these fields. Use the datetimeSeparators option for additional/alternate separators. This is one of the regional settings fields.

$(selector).datetimeEntry({datetimeFormat: 'd n Y H:M'});
$(selector).datetimeEntry({datetimeFormat: 'Y-O-DTH:M:S'});
$(selector).datetimeEntry({datetimeFormat: 'D/M/Y'});
$(selector).datetimeEntry({datetimeFormat: 'H:M:S'});
datetimeSeparatorsstring'.' The set of additional characters (beyond those in datetimeFormat) to use to move from one sub-field to the next. This is one of the regional settings fields.

$(selector).datetimeEntry({datetimeSeparators: '.-'});
monthNamesstring[12]['January', ..., 'December'] The names of the months. This is one of the regional settings fields.
monthNamesShortstring[12]['Jan', ..., 'Dec'] The abbreviated names of the months. This is one of the regional settings fields.
dayNamesstring[7]['Sunday', ..., 'Saturday'] The names of the days, starting at Sunday. This is one of the regional settings fields.
dayNamesShortstring[7]['Sun', ..., 'Sat'] The abbreviated names of the days, starting at Sunday. This is one of the regional settings fields.
ampmNamesstring[2]['AM', 'PM'] The AM/PM indicators. This is one of the regional settings fields.
isRTLbooleanfalse Set to true to indicate that this language runs right-to-left. This is one of the regional settings fields.
appendTextstring'' Add content to display after each date field. This may contain HTML markup.
initialFieldnumber0 The number of the portion of the date field to highlight initially. Use 0 for the first field.
useMouseWheelbooleantrue True to use the mouse wheel for increment/decrement if possible, false to never use it.
shortYearCutoffnumber or string'+10' The cutoff point for determining the century for a short year (for 'y' in datetimeFormat). If a number is provided it is used as is. If a string value is provided it is converted to a number and added to the current year. When a short year is entered that is greater than this value it is moved to the previous century.

$(selector).datetimeEntry({datetimeFormat: 'd n y H:M', shortYearCutoff: 50});
defaultDatetimeDate or number or stringnull The default date/time to show when no other value has been entered. This may be a Date object, a string in the current datetimeFormat, a numeric value indicating seconds from now, or a string value indicating a number and units. In the latter case, use 'y' for years, 'o' for months, 'w' for weeks, 'd' for days, 'h' for hours, 'm' for minutes, or 's' for seconds. Letters may be upper or lower case. Multiple offsets may be combined into one setting. Leave as null to default to the current date.

$(selector).datetimeEntry({defaultDatetime: new Date(2009, 12 - 1, 25, 11, 30)});
$(selector).datetimeEntry({defaultDatetime: '12/25/2009 11:30AM'});
$(selector).datetimeEntry({defaultDatetime: +1});
$(selector).datetimeEntry({defaultDatetime: '+1o -1d'});
minDatetimeDate or number or stringnull The minimum date/time that may be selected, or null for no limit. See defaultDatetime for a description of the possible formats.
maxDatetimeDate or number or stringnull The maximum date/time that may be selected, or null for no limit. See defaultDatetime for a description of the possible formats.
minTimeDate or number or stringnull The minimum time that may be selected regardless of the date, or null for no limit. See defaultDatetime for a description of the possible formats.

$(selector).datetimeEntry({minTime: new Date(0, 0, 0, 8, 30)});
$(selector).datetimeEntry({minTime: -300});
maxTimeDate or number or stringnull The maximum time that may be selected regardless of the date, or null for no limit. See defaultDatetime for a description of the possible formats.

$(selector).datetimeEntry({maxTime: new Date(0, 0, 0, 17, 30)});
$(selector).datetimeEntry({maxTime: +300});
timeStepsnumber[3][1, 1, 1] The increment/decrement values for each of the time portions - hours, minutes, and seconds. Use this to constrain the portions, e.g. the following restricts the times to quarter hours.

$(selector).datetimeEntry({timeSteps: [1, 15, 0]});
spinnerImagestring'spinnerDefault.png' The URL for the spinner images to use, or '' for no spinner. The file must contain seven images horizontally for the normal view, then for each "button" pressed (now, previous, next, increment, and decrement), and, finally, the disabled view.

Sample spinner image
spinnerSizenumber[3][20, 20, 8] The dimensions of the spinner image for determining which "button" was clicked. The first two values are the width and height of the individual images, the third is the size of the central button for setting the current date, or 0 for no central button.
spinnerBigImagestring'' The URL for an expanded spinner image to use, or '' for no expansion. The layout is the same as for spinnerImage but should be a larger size. The expanded spinner appears when the user hovers over the original spinner and disappears when they move off it.
spinnerBigSizenumber[3][40, 40, 16] The dimensions of the expanded spinner image for determining which "button" was clicked. The first two values are the width and height of the individual images, the third is the size of the central button for setting the current date, or 0 for no central button.
spinnerIncDecOnlybooleanfalse True to have only the increment and decrement buttons on the spinner, or false for all the buttons.
spinnerTextsstring[5] ['Today', 'Previous field', 'Next field', 'Increment', 'Decrement'] The tooltip text for the spinner buttons. This is one of the regional settings fields.
spinnerRepeatnumber[2][500, 250] The times in milliseconds for the auto-repeat feature on the increment and decrement spinner buttons. The first value is the initial delay and the second one is the subsequent delay. Hold the mouse button down on these spinner buttons to trigger this feature. Use [0, 0] to disable the auto-repeat.
beforeShowfunctionnull A function that accepts an input field and returns a settings object containing new settings for the date/time entry for this field. For example, you can use it to set up a date/time range wherein both fields restrict the possible values of the other field. this refers to the input field as well. Leave as null for no per-field customisation.

$(selector).datetimeEntry({beforeShow: customRange});

function customRange(input) {
	return {minDatetime: (input.id == 'dtTo' ?
		$('#dtFrom').datetimeEntry('getDatetime') : null), 
		maxDatetime: (input.id == 'dtFrom' ?
		$('#dtTo').datetimeEntry('getDatetime') : null)};
}
altFieldstring or element or jQuerynull Specify another field to be updated in sync with the date/time entry. This and the following setting allow you to automatically show selected date/times in one format for the user, while maintaining a second field with a more useful format for further processing. The alternate field may be specified as either the element itself, a jQuery collection containing the element, or a string selector for the desired element.

$(selector).datetimeEntry({
    altField: '#isoDatetime', altFormat: 'Y-O-DTH:M:S'});
altFormatstringnull Use in conjunction with the altField setting to automatically maintain two different views of the entered date/time. See the datetimeFormat setting for the list of possible values.

Global Settings

NameTypeDefaultComments
regionalobject[] The set of regional settings for the date/time entry fields. Entries are indexed by the country/region code with '' providing the default (English) settings. Each entry is an anonymous object with the following properties: datetimeFormat, datetimeSeparators, monthNames, monthNamesShort, dayNames, dayNamesShort, ampmNames, spinnerTexts, isRTL. Language packages load new entries into this array and automatically apply them as global defaults.

<script type="text/javascript" src="jquery.datetimeentry-fr.js"></script>

If necessary, you can then revert to the default language settings with

$.datetimeEntry.setDefaults($.datetimeEntry.regional['']);

and apply the language settings to individual fields with

$('#frenchDate').datetimeEntry($.datetimeEntry.regional['fr']);

Check out the list of available localisation packages.

Functions

change | destroy | disable | enable | getDatetime | getOffset | isDisabled | setDatetime | setDefaults

SignatureReturnsComments
$.datetimeEntry.setDefaults(settings)- Update the default instance settings to use with all date/time entry instances.
$(selector).datetimeEntry('change', settings)jQuery Update the settings for the date/time entry instance(s) attached to the given input field(s).

settings (object) the new settings to use.

$(selector).datetimeEntry('change',
	{minDatetime: new Date(2009, 12 - 1, 25, 11, 30)});
$(selector).datetimeEntry('change',
	{initialField: 1, useMouseWheel: false});
$(selector).datetimeEntry('change', name, value)jQuery Update a single setting for the date/time entry instance(s) attached to the given input field(s).

name (string) the name of the option;

value (any) the option's new value.

$(selector).datetimeEntry('change',
	'minDatetime', new Date(2009, 12 - 1, 25, 11, 30));
$(selector).datetimeEntry('change', 'initialField', 1);
$(selector).datetimeEntry('destroy')jQuery Remove the date/time entry functionality from the given input field(s).
$(selector).datetimeEntry('disable')jQuery Disable the given input field and any spinner attached to it, preventing it from being used for date/time entry.
$(selector).datetimeEntry('enable')jQuery Enable the given input field and any spinner attached to it, allowing it to be used for date/time entry.
$(selector).datetimeEntry('isDisabled')boolean Determine whether the (first) given input field has been disabled (true).
$(selector).datetimeEntry('setDatetime', datetime)jQuery Update and display the date/time in the correct format for the given input field(s). See defaultDatetime for a description of the possible formats for datetime.

datetime (Date or string or number) the new date/time to use, which may be a Date object, a string in the current datetimeFormat, a numeric value (seconds from now, e.g. +10), or a string value indicating a number and units, e.g. '+2w'. In the latter case, use 'y' for years, 'o' for months, 'w' for weeks, 'd' for days, 'h' for hours, 'm' for minutes, or 's' for seconds. Letters may be upper or lower case. Multiple offsets may be combined into one setting, e.g. '-1o -10d'. Use 0 for the current date/time. Use null or '' to clear the date/time.

$(selector).datetimeEntry('setDatetime',
	new Date(2009, 12 - 1, 25, 11, 30));
$(selector).datetimeEntry('setDatetime', '12/25/2009 11:30AM');
$(selector).datetimeEntry('setDatetime', +180);
$(selector).datetimeEntry('setDatetime', '+1o -1d');

Since 1.0.1 - null or '' clears the date/time.
$(selector).datetimeEntry('getDatetime')Date Retrieve the date/time for the (first) given input field as a Date. Returns null if the field is blank.
$(selector).datetimeEntry('getOffset')number Retrieve the time portion of the selected date/time as a millisecond offset for the (first) given input field. This can be used to add to a midnight Date object to set its time. Returns 0 if the field is blank.

var dt = new Date(2010, 1-1, 26);
dt.setTime(dt.getTime() + $(selector).datetimeEntry('getOffset'));

Contact Keith Wood at kbwood{at}iinet.com.au with comments or suggestions.

Valid HTML 4.01 Strict