jQuery Date Entry

Default Settings

The date entry functionality can easily be added to an input field with appropriate default settings. Also shown is the control's appearance when disabled.

Default date entry:

$('#defaultEntry').dateEntry().change(function() {
	var log = $('#log');
	log.val(log.val() + ($('#defaultEntry').val() || 'blank') + '\n');
});

On change log:

The defaults are:

Text is in English
Date format is mm/dd/yyyy
Subfields selectable by mouse click
No date restrictions
Spinner is displayed
Spinner auto-repeats on increment/decrement
Mouse wheel increment/decrement (with jquery.mousewheel.js)
Field's on change event fires (see to the right)

You can enable or disable date entry fields.

$('#disableDefault').click(function() {
	var disable = $(this).text() === 'Disable';
	$(this).text(disable ? 'Enable' : 'Disable');
	$('#defaultEntry').dateEntry(disable ? 'disable' : 'enable');
});

Or completely remove the date entry functionality.

$('#removeDefault').click(function() {
	var destroy = $(this).text() === 'Remove';
	$(this).text(destroy ? 'Re-attach' : 'Remove');
	$('#defaultEntry').dateEntry(destroy ? 'destroy' : {});
});

You can override the defaults globally as shown below:

$.dateEntry.setDefaults({spinnerImage: 'img/spinnerDefault.png'});

Processed fields are marked with a class of is_dateEntry and are not re-processed if targeted a second time.

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).dateEntry({minDate: new Date(2010, 12-1, 25)});

Keystrokes

The date entry field also responds to keystrokes. You may also specify alternate separators for keyed entry. In this case you can use '/', '.', or '-'.

Keyboard driven:

Tab to exit

$('#keyedEntry').dateEntry({dateFormat: 'mdy/.-'});

$('#tabToExit').change(function() {
	$('#keyedEntry').dateEntry('option', 'tabToExit', $(this).is(':checked'));
});

The relevant keystrokes are:

0 - 9direct date entry
(separator(s))move to next date portion
down/updecrement/increment current date portion
left/rightmove to previous/next date portion
shift+/tabmove to previous/next date portion (unless flagged to exit)
home/endmove to the first/last date portion
ctrl+homeset to the current date
ctrl+end or deleteclear the date

Date Formats

You can control how the date is presented. The dateFormat setting consists of three characters indicating the order of the fields - 'y' for four-digit year, 'Y' for two-digit-year, 'm' for month, 'n' for abbreviated month name, 'N' for full month name, 'd' for day, 'w' for abbreviated day of the week and day, 'W' for full day of the week and day - followed by one or more separator characters.

European format:

$('#europeEntry').dateEntry({dateFormat: 'dmy/'});

ISO format:

$('#isoEntry').dateEntry({dateFormat: 'ymd-'});

Short year:

$('#shortEntry').dateEntry({dateFormat: 'dmY/'});

Alternate separators (/,-,.):

$('#separatorsEntry').dateEntry({dateFormat: 'dmy/-.'});

Textual month:

$('#monthEntry').dateEntry({dateFormat: 'dny '});

Textual day:

$('#dayEntry').dateEntry({dateFormat: 'wny '});

Full day and month:

$('#fullEntry').dateEntry({dateFormat: 'WNy '});

Day and month only:

$('#dayMonthEntry').dateEntry({dateFormat: 'dm /'});

Month and year only:

$('#monthYearEntry').dateEntry({dateFormat: 'Ny  '});

Interact with the inputs: Absolute Relative

When setting the date you can provide a Date object, or a number for days from now, or a string containing the period and units: 'y' for years, 'm' for months, 'w' for weeks, or 'd' for days. Letters may be upper or lower case. Multiple offsets may be combined into the one setting.

$('#getTheDate').click(function() {
	alert('The date is ' + $('#' + $('#pickInput').val()).
		dateEntry('getDate'));
});
$('#setTheDate').click(function() {
	var date = ($('#abs').is(':checked') ?
		new Date(2014, 1 - 1, 26) : '+1m +1w');
	$('#' + $('#pickInput').val()).dateEntry('setDate', date);
});

Date Restrictions

You can restrict the functionality of the date entry fields in various ways. Such as limiting the range of dates selectable within the field.

Limited dates:

$('#restrictRange').dateEntry({minDate: new Date(2013, 1 - 1, 26), 
	maxDate: new Date(2014, 1 - 1, 26)});

The range of selectable dates can also be set as relative to the current date. Use a number for days from now, or a string containing the period and units: 'y' for years, 'm' for months, 'w' for weeks, or 'd' for days. Letters may be upper or lower case. Multiple offsets may be combined into the one setting.

Relative limited dates:

$('#restrictRelative').dateEntry({minDate: -7, maxDate: '+1m +1w'});

Miscellaneous Features

To make it easier to use the spinner, you can set it to expand on hover.

Expanded spinner:

$('#expandedSpinner').dateEntry(
	{spinnerBigImage: 'img/spinnerDefaultBig.png'});

$('#enableSpinner').click(function() {
	var disable = $(this).text() === 'Disable';
	$(this).text(disable ? 'Enable' : 'Disable');
	$('#expandedSpinner').dateEntry(disable ? 'disable' : 'enable');
});

You can set an alternate field to be kept synchronised with the date entry field, and it may have a different format. Use this to display more user-friendly text while passing a more easily used format to the server.

Alternate field:

$('#withAlternate').dateEntry({dateFormat: 'wnY ',
	altField: '#alternateField', altFormat: 'ymd-'});

You can set which portion of the date should be initially highlighted.

Highlight middle field:

$('#highlightDays').dateEntry({initialField: 1});

You can set a default date to show when nothing has been selected. If this setting is not specified, it defaults to the current date.

Absolute default date:

$('#absoluteDefault').dateEntry(
	{defaultDate: new Date(2014, 1 - 1, 26)});

Alternatively, the default date can be set relative to the current date. Use a number for days from now, or a string containing the period and units: 'y' for years, 'm' for months, 'w' for weeks, or 'd' for days. Letters may be upper or lower case. Multiple offsets may be combined into the one setting.

Relative default date:

$('#relativeDefault').dateEntry({defaultDate: '+1m +1w'});

Date Range

Use a custom field settings function to create a date range control: two date fields, each restricting the other. The function takes an input field as an argument and returns a settings object.

Date range: to

$('.dateRange').dateEntry({beforeShow: customRange});

function customRange(input) {
	return {minDate: (input.id === 'dTo' ?
		$('#dFrom').dateEntry('getDate') : null), 
		maxDate: (input.id === 'dFrom' ?
		$('#dTo').dateEntry('getDate') : null)};
}

Spinner Settings

Change the spinner. The first one has no central "Now" button, while the last has only the increment and decrement buttons.

Alternate spinners: Expand

Specify the size of the new spinner image (width and height) along with the size of the central button (0 for none) so that the location of the individual "buttons" can be determined. Suppress the previous/next buttons with spinnerIncDecOnly.

$('#spinnerSquare').dateEntry({spinnerImage: 'img/spinnerSquare.png',
	spinnerSize: [20, 20, 0], spinnerBigSize: [40, 40, 0]});
$('#spinnerOrange').dateEntry({spinnerImage: 'img/spinnerOrange.png'});
$('#spinnerText').dateEntry({spinnerImage: 'img/spinnerText.png',
	spinnerSize: [30, 20, 8], spinnerBigSize: [60, 40, 16]});
$('#spinnerGem').dateEntry({spinnerImage: 'img/spinnerGem.png'});
$('#spinnerUpDown').dateEntry({spinnerImage: 'img/spinnerUpDown.png',
	spinnerSize: [15, 16, 0], spinnerBigSize: [30, 32, 0],
	spinnerIncDecOnly: true});
	
$('#expand').change(function() {
	var expanded = $(this).is(':checked');
	$('input.spinners').each(function() {
		$(this).dateEntry('option', {spinnerBigImage:
			(expanded ? 'img/' + this.id + 'Big.png' : '')});
	});
});

$('#disableSpinners').click(function() {
	var disable = $(this).text() === 'Disable';
	$(this).text(disable ? 'Enable' : 'Disable');
	$('input.spinners').dateEntry(disable ? 'disable' : 'enable');
});

Disable auto-repeat:

$('#disableRepeat').dateEntry({spinnerRepeat: [0, 0]});

No mouse wheel support:

$('#noMouseWheel').dateEntry({useMouseWheel: false});

No spinner image:

$('#noSpinnerEntry').dateEntry({spinnerImage: ''});

Inline Configuration

Instead of configuring date entry fields via parameters to the instantiation call, you can specify many of them inline in the data-dateEntry attribute.

Inline configuration 1:

Inline configuration 2:

<input type="text" size="10" class="inlineConfig"
	data-dateEntry="useMouseWheel: false, dateFormat: 'dmy-', appendText: ' (see below)'">
	
<input type="text" size="10" class="inlineConfig"
	data-dateEntry="minDate: 'new Date(2013, 1 - 1, 26)', maxDate: 'new Date(2014, 1 - 1, 26)'">

$('.inlineConfig').dateEntry();

Or reconfigure on the fly.

Reconfiguration:

$('#reConfig').dateEntry({dateFormat: 'mdy/'});
		
$('#switchButton').click(function() {
	var format = $('#reConfig').dateEntry('option', 'dateFormat') === 'mdy/' ? 'ymd-' : 'mdy/';
	$('#reConfig').dateEntry('option', {dateFormat: format});
});

Localisation

You can localise the date entry fields for other languages and regional differences. The date entry defaults to English with a date format of mm/dd/yyyy. Select a language to change the date format and spinner tooltips.

:

You need to load the appropriate language package (see list below), which adds a language set ($.dateEntry.regionalOptions[langCode]) and automatically sets this language as the default for all date entry fields.

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

Thereafter, if desired, you can restore the original language settings.

$.dateEntry.setDefaults($.dateEntry.regionalOptions['']);

And then configure the language per date entry field.

$('#l10nDate').dateEntry($.dateEntry.regionalOptions['fr']);
$('#l10n2Date').dateEntry($.extend({},
	$.dateEntry.regionalOptions['fr'], {dateFormat: 'wny '}));
$('#l10n3Date').dateEntry($.extend({},
	$.dateEntry.regionalOptions['fr'], {dateFormat: 'WNy '}));
$('#language').change(localise);

In the Wild

This tab highlights examples of this plugin in use "in the wild".

None as yet.

To add another example, please contact me (wood.keith{at}optusnet.com.au) and provide the plugin name, the URL of your site, its title, and a short description of its purpose and where/how the plugin is used.

Quick Reference

A full list of all possible settings is shown below. Note that not all would apply in all cases. For more detail see the documentation reference page.

$(selector).dateEntry({
	dateFormat: 'mdy/', // The format of the date text:
		// first three fields in order ('y' for year, 'Y' for two-digit year,
		// 'm' for month, 'n' for abbreviated month name, 'N' for full month name,
		// 'd' for day, 'w' for abbreviated day name and number,
		// 'W' for full day name and number), followed by separator(s) 
	monthNames: ['January', 'February', 'March', 'April', 'May', 'June',
		'July', 'August', 'September', 'October', 'November', 'December'],
		// Names of the months
	monthNamesShort: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
		'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'], // Abbreviated names of the months
	dayNames: ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'],
		// Names of the days
	dayNamesShort: ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'],
		// Abbreviated names of the days
	spinnerTexts: ['Today', 'Previous field', 'Next field', 'Increment', 'Decrement'],
		// The popup texts for the spinner image areas

	appendText: '', // Display text following the input box, e.g. showing the format
	initialField: null, // The field to highlight initially,
		// use 0 for the first field, or null for user selection
	tabToExit: false, // True for tab key to go to next element,
		// false for tab key to step through internal fields
	useMouseWheel: true, // True to use mouse wheel for increment/decrement if possible,
		// false to never use it
	defaultDate: null, // The date to use if none has been set, leave at null for now
	minDate: null, // The earliest selectable date, or null for no limit
	maxDate: null, // The latest selectable date, or null for no limit
	spinnerImage: 'spinnerDefault.png', // The URL of the images to use for the date spinner
		// Seven images packed horizontally for normal, each button pressed, and disabled
	spinnerSize: [20, 20, 8], // The width and height of the spinner image,
		// and size of centre button for current date
	spinnerBigImage: '', // The URL of the images to use for the expanded date spinner
		// Seven images packed horizontally for normal, each button pressed, and disabled
	spinnerBigSize: [40, 40, 16], // The width and height of the expanded spinner image,
		// and size of centre button for current date
	spinnerIncDecOnly: false, // True for increment/decrement buttons only, false for all
	spinnerRepeat: [500, 250], // Initial and subsequent waits in milliseconds
		// for repeats on the spinner buttons
	beforeShow: null, // Function that takes an input field and
		// returns a set of custom settings for the date entry
	altField: null, // Selector, element or jQuery object for an alternate field to keep synchronised
	altFormat: null // A separate format for the alternate field
});

$.dateEntry.regionalOptions[] // Language/country-specific localisations

$.dateEntry.setDefaults(settings) // Set default values for all instances

$(selector).dateEntry('option', settings) // Change the settings for selected instances
$(selector).dateEntry('option', name, value) // Change a single setting for selected instances
$(selector).dateEntry('option', name) // Retrieve a setting value

$(selector).dateEntry('destroy') // Remove the date entry functionality

$(selector).dateEntry('disable') // Disable date entry

$(selector).dateEntry('enable') // Enable date entry

$(selector).dateEntry('isDisabled') // Determine if field is disabled

$(selector).dateEntry('setDate', date) // Set the date for the instance

$(selector).dateEntry('getDate') // Retrieve the currently selected date

Version	Date	Changes
2.0.1	31 May 2014	Added ' ' to `dateFormat` to allow for day/month or month/year only combinations Defaulted `initialField` to `null` for user selection (Thanks to Jesse Rosenberg) Added Farsi and Lithuanian localisations
2.0.0	11 Jan 2014	Updated underlying plugin framework Added `tabToExit` option to control tabbing Changed `regional` to `regionalOptions` Marker class changed from `hasDateEntry` to `is-dateEntry` Reset character input on changing fields Added Arabic localisation
1.1.1	16 Mar 2013	Updated for jQuery 1.9 Removed input wrapper
1.1.0	19 Jan 2013	Changed `change` command to `option` Added option retrieval Updated underlying plugin framework Keydown processing returns `true` for unhandled keystrokes Corrected metadata usage Added Slovenian localisation
1.0.6	26 Mar 2011	Added `altField` and `altFormat` settings Using `setDate` command with `null` or '' clears the date Allow direct entry by month name All dates now have time portion set to 12 noon `disable` command prevents the spinner expanding Added Danish and Greek localisations
1.0.5	01 May 2010	`defaultDate`, `minDate`, and `maxDate` may be set as a date string in the current date format Allow multiple separators on keyboard input Added 'Y' format for two-digit year Added single value option for 'change' command
1.0.4	24 Oct 2009	Handle midnight changes for daylight saving
1.0.3	29 Aug 2009	Updated direct entry to allow more single digit values Added Icelandic localisation
1.0.2	04 Jul 2009	Changed inline configuration to work from metadata in `class` attribute Ensure focus when mouse wheel is used Added Japanese and Vietnamese localisations
1.0.1	23 May 2009	Handle expanded spinner in `relative` container Only trigger the field change event if the value actually changed Corrected stealing of focus on spinner over/out Corrected field highlighting on initial focus and with text alignment Tuned sub-field determination in IE
1.0.0	14 Mar 2009	Initial release