jQuery Time Entry

Default Settings

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

Default time entry:   Disable  Remove

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

The defaults are:

• Text is in English
• Time format is HH:MMAP - 12 hour time
• Increment/decrement all fields by one
• Subfields selectable by mouse click
• No time 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 time entry fields.

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

Or completely remove the time entry functionality.

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

You can override the defaults globally as shown below:

$.timeEntry.setDefaults({show24Hours: true});

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

Keystrokes

The time entry field also responds to keystrokes.

Keyboard driven:

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

The relevant keystrokes are:

• 0 - 9direct time entry
• : (separator)move to next time portion
• A/P (AM/PM values)set AM/PM
   
• down/updecrement/increment current time portion
• left/rightmove to previous/next time portion
• shift+/tabmove to previous/next time portion
• home/endmove to the first/last time portion
• ctrl+homeset to the current time
• ctrl+end or deleteclear the time

Time Formats

You can control how the time is presented.

Show seconds:

$('#showSeconds').timeEntry({showSeconds: true});

Show 24 hour time:

$('#show24').timeEntry({show24Hours: true});

Separate AM/PM:

$('#separateAmpm').timeEntry({ampmPrefix: ' '});

Change the separator:

$('#showSeparator').timeEntry({separator: '.'});

No separator:

$('#noSeparator').timeEntry({separator: ''});

Interact with the inputs: Show seconds Show 24 hour time Separate AM/PM Change the separator No separator Get time Set time Absolute Relative

When setting the time you can provide a Date object, or a number for seconds from now, or a string containing the period and units: 'H' for hours, 'M' for minutes, or 'S' for seconds. Letters may be upper or lower case. Multiple offsets may be combined into the one setting. Prefix with '!' to prevent a wrap around into another day.

function getTheTime() {
	alert('The time is ' +
		$('#' + $('#pickInput').val()).timeEntry('getTime'));
}

function setTheTime() {
	var time = ($('#abs').is(':checked') ?
		new Date(0, 0, 0, 16, 7, 11) : '+1h +30m');
	$('#' + $('#pickInput').val()).timeEntry('setTime', time);
}

$('#getTheTime').click(getTheTime);
$('#setTheTime').click(setTheTime);

Time Restrictions

You can restrict the functionality of the time entry fields in various ways. The first example only allows selection of times in quarter hour increments by setting the steps for each of hours, minutes, and seconds.

Restricted time increments:

$('#restrictSteps').timeEntry({timeSteps: [1, 15, 0]});

You can also limit the range of times selectable within the field. Here it's between 8:30AM and 5:30PM.

Limited times:

$('#restrictRange').timeEntry({minTime: new Date(0, 0, 0, 8, 30, 0), 
	maxTime: new Date(0, 0, 0, 17, 30, 0)});

The range of selectable times can also be set as times relative to the current time. Use a number for seconds from now, or a string containing the period and units: 'H' for hours, 'M' for minutes, or 'S' for seconds. Letters may be upper or lower case. Multiple offsets may be combined into the one setting. Prefix with '!' to prevent a wrap around into another day.

Relative limited times:

$('#restrictRelative').timeEntry({minTime: -600, maxTime: '!+2h'});

Additional restrictions can be applied via a callback function that is called just before setting a new time for the field. Here only times in the first half of each hour are accepted.

Additional restriction:

$('#restrictTime').timeEntry({beforeSetTime: firstHalfHourOnly});

function firstHalfHourOnly(oldTime, newTime, minTime, maxTime) {
	var increment = (newTime - (oldTime || newTime)) > 0;
	if (newTime.getMinutes() > 30) {
		newTime.setMinutes(increment ? 0 : 30);
		newTime.setHours(newTime.getHours() + (increment ? 1 : 0));
	}
	return newTime;
}

Miscellaneous Features

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

Expanded spinner:

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

You can set which portion of the time should be initially highlighted. Use 0 for hours, 1 for minutes, etc.

Highlight minutes:

$('#highlightMins').timeEntry({initialField: 1});

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

Absolute default time:

$('#absoluteDefault').timeEntry(
	{defaultTime: new Date(0, 0, 0, 11, 11, 11)});

Alternatively, the default time can be set relative to the current time. Use a number for seconds from now, or a string containing the period and units: 'H' for hours, 'M' for minutes, or 'S' for seconds. Letters may be upper or lower case. Multiple offsets may be combined into the one setting. Prefix with '!' to prevent a wrap around into another day.

Relative default time:

$('#relativeDefault').timeEntry({defaultTime: '+1h +30m'});

Time Range

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

Time range: to

$('.timeRange').timeEntry({beforeShow: customRange});

function customRange(input) {
	return {minTime: (input.id == 'tTo' ?
		$('#tFrom').timeEntry('getTime') : null), 
		maxTime: (input.id == 'tFrom' ?
		$('#tTo').timeEntry('getTime') : 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').timeEntry({spinnerImage: 'img/spinnerSquare.png',
	spinnerSize: [20, 20, 0], spinnerBigSize: [40, 40, 0]});
$('#spinnerOrange').timeEntry({spinnerImage: 'img/spinnerOrange.png'});
$('#spinnerText').timeEntry({spinnerImage: 'img/spinnerText.png',
	spinnerSize: [30, 20, 8], spinnerBigSize: [60, 40, 16]});
$('#spinnerGem').timeEntry({spinnerImage: 'img/spinnerGem.png'});
$('#spinnerUpDown').timeEntry({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).timeEntry('change',
			{spinnerBigImage: (expanded ? 'img/' + this.id + 'Big.png' : '')});
	});
});

Disable auto-repeat:

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

No mouse wheel support:

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

No spinner image:

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

Inline Configuration

Instead of configuring time 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
	{show24Hours: true, timeSteps: [1, 30, 0], appendText: ' (see below)'}">
	
<input type="text" size="10" class="inlineConfig
	{minTime: new Date(0, 0, 0, 0, 0, 0), maxTime: new Date(0, 0, 0, 11, 59, 0)}">

$('.inlineConfig').timeEntry();

Or reconfigure on the fly.

Reconfiguration: Switch formats

$('#reConfig').timeEntry({showSeconds: true});
$('#switchButton').toggle(
	function() { $('#reConfig').timeEntry('change', 
		{show24Hours: true, showSeconds: false}); },
	function() { $('#reConfig').timeEntry('change',
		{show24Hours: false, showSeconds: true}); }
);

Localisation

You can localise the time entry fields for other languages and regional differences. The time entry defaults to English with a time format of HH:MMAP. Select a language to change the time 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 ($.timeEntry.regional[langCode]) and automatically sets this language as the default for all time entry fields.

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

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

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

And then configure the language per time entry field.

$('#l10nTime').timeEntry($.timeEntry.regional['fr']);
$('#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.

Backwards Compatibility

Several interface changes were made between v1.2.6 and v1.3.0 to bring this plugin into line with the new UI interface standards.

To assist in the upgrade process, a compatibility module is available that allows a v1.2.6 page to be run against the latest code.

Just add the following line to your page after the plugin load to continue running:

<script type="text/javascript" src="jquery.timeentry.compat-1.2.6.js"></script>

To complete the upgrade perform the following steps:

• Replace $.timeEntry.reconfigureFor(…, …) with $(…).timeEntry('change', …)
• Replace $.timeEntry.enableFor(…, …) with $(…).timeEntry('enable', …)
• Replace $.timeEntry.disableFor(…, …) with $(…).timeEntry('disable', …)
• Replace $.timeEntry.isDisabled(…) with $(…).timeEntry('isDisabled')
• Replace $.timeEntry.setTimeFor(…, …) with $(…).timeEntry('setTime', …)
• Replace $.timeEntry.getTimeFor(…) with $(…).timeEntry('getTime')

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).timeEntry({
	show24Hours: false, // True to use 24 hour time, false for 12 hour (AM/PM)
	separator: ':', // The separator between time fields
	ampmPrefix: '', // The separator before the AM/PM text
	ampmNames: ['AM', 'PM'], // Names of morning/evening markers
	// The popup texts for the spinner image areas
	spinnerTexts: ['Now', 'Previous field', 'Next field', 'Increment', 'Decrement']
	
	appendText: '', // Display text following the input box, e.g. showing the format
	showSeconds: false, // True to show seconds as well, false for hours/minutes only
	timeSteps: [1, 1, 1], // Steps for each of hours/minutes/seconds when incrementing/decrementing
	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
	defaultTime: null, // The time to use if none has been set, leave at null for now
	minTime: null, // The earliest selectable time, or null for no limit
	maxTime: null, // The latest selectable time, or null for no limit
	spinnerImage: 'spinnerDefault.png', // The URL of the images to use for the time 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 time
	spinnerBigImage: '', // The URL of the images to use for the expanded time 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 time
	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 time entry
	beforeSetTime: null // Function that runs before updating the time,
		// takes the old and new times, and minimum and maximum times as parameters,
		// and returns an adjusted time if necessary
});

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

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

$(selector).timeEntry('destroy') // Remove the time entry functionality

$(selector).timeEntry('disable') // Disable time entry

$(selector).timeEntry('enable') // Enable time entry

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

$(selector).timeEntry('setTime', time) // Set the time for the instance

$(selector).timeEntry('getTime') // Retrieve the currently selected time