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:   Disable  Remove

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

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.

$('#enableDefault').toggle(
	function() {
		$(this).text('Enable');
		$('#defaultEntry').dateEntry('disable');
	},
	function() {
		$(this).text('Disable');
		$('#defaultEntry').dateEntry('enable');
	});

Or completely remove the date entry functionality.

$('#removeDefault').toggle(
	function() {
		$(this).text('Re-attach');
		$('#defaultEntry').dateEntry('destroy'); }, 
	function() {
		$(this).text('Remove');
		$('#defaultEntry').dateEntry();
	});

You can override the defaults globally as shown below:

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

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

Keystrokes

The date entry field also responds to keystrokes.

Keyboard driven:

$('#keyedEntry').dateEntry();

The relevant keystrokes are:

• 0 - 9direct date entry
• / (separator)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
• 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 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 the separator character.

European format:

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

ISO format:

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

Textual month:

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

Textual day:

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

Full day and month:

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

Interact with the inputs: European entry ISO entry Textual month Textual day Get date Set date 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.

function getTheDate() {
	alert('The date is ' + $('#' + $('#pickInput').val()).
		dateEntry('getDate'));
}

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

$('#getTheDate').click(getTheDate);
$('#setTheDate').click(setTheDate);

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(2008, 1 - 1, 26), 
	maxDate: new Date(2009, 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'});

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(2009, 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');
	$('.spinners').each(function() {
		$(this).dateEntry('change', {spinnerBigImage:
			(expanded ? 'img/' + this.id + 'Big.png' : '')});
	});
});

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 them inline. You must add the jQuery Metadata plugin to your page and then encode the settings in the class attribute (by default).

Inline configuration 1:

Inline configuration 2:

<input type="text" size="10" class="inlineConfig
	{useMouseWheel: false, dateFormat: 'dmy-', appendText: ' (see below)'}">
	
<input type="text" size="10" class="inlineConfig
	{minDate: new Date(2008, 1 - 1, 26), maxDate: new Date(2009, 1 - 1, 26)}">

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

Or reconfigure on the fly.

Reconfiguration: Switch formats

$('#reConfig').dateEntry({dateFormat: 'mdy/'});
$('#switchButton').toggle(
	function() { $('#reConfig').dateEntry(
		'change', {dateFormat: 'ymd-'}); },
	function() { $('#reConfig').dateEntry(
		'change', {dateFormat: 'mdy/'}); }
);

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/yy. Select a language to change the date format and spinner tooltips.

Čeština (Czech) Deutsch (German) Español (Spanish) Français (French) Íslenska (Icelandic) Italiano (Italian) Magyar (Hungarian) Nederlands (Dutch) 日本語 (Japanese) Polski (Polish) Português (Portugese) Română (Romanian) Русский (Russian) Slovenčina (Slovak) Svenska (Swedish) Tiếng Việt (Vietnamese) Türkçe (Turkish) 简体中文 (Simplified Chinese) :

 

 

You need to load the appropriate language package (see list below), which adds a language set ($.dateEntry.regional[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.regional['']);

And then configure the language per date entry field.

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

In the Wild

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

To add another example, please contact me (kbwood{at}iinet.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, '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 
	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: 0, // The field to highlight initially, 0 = hours, 1 = minutes, ...
	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
});

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

$(selector).dateEntry('change', settings) // Change the settings for selected instances

$(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