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:    

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

On change log:

The defaults are:

You can enable or disable time entry fields.

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

Or completely remove the time entry functionality.

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

You can override the defaults globally as shown below:

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

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

Keystrokes

The time entry field also responds to keystrokes.

Keyboard driven:

 

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

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

The relevant keystrokes are:

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: ''});

Unlimited hours:

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

Unlimited hours (seconds):

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

Interact with the inputs:

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.

$('#getTheTime').click(function() {
	alert('The time is ' +
		$('#' + $('#pickInput').val()).timeEntry('getTime'));
});
$('#setTheTime').click(function() {
	var time = ($('#abs').is(':checked') ?
		new Date(0, 0, 0, 16, 7, 11) : '+1h +30m');
	$('#' + $('#pickInput').val()).timeEntry('setTime', time);
});
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 as Dates:

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

Limited times as strings:

$('#restrictStrRange').timeEntry({
	minTime: '08:30AM', maxTime: '05:30PM'});

If the minimum time is greater than the maximum time, then it only allows the period between the minimum and the maximum "next day".

Overnight limit:

$('#overnightTimeRange').timeEntry({minTime: new Date(0, 0, 0, 18, 30, 0), 
	maxTime: new Date(0, 0, 0, 5, 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'});

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

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});

Allow direct entry of a time without typing separators.

No separator entry:

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

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.

Default time as a Date:

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

Default time as a string:

$('#absoluteStrEntry').timeEntry({defaultTime: '12:34PM'});

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.

Default time as a numeric offset:

$('#relativeNumEntry').timeEntry({defaultTime: -300});

Default time as a string offset:

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

Retrieve the millisecond offset for the selected time. This value could be added to a midnight Date to set its time.

Millisecond offset:

$('#offsetEntry').timeEntry();
$('#offsetButton').click(function() {
	alert('Milliseconds = ' + $('#offsetEntry').timeEntry('getOffset'));
});
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 === 'timeTo' ?
		$('#timeFrom').timeEntry('getTime') : null), 
		maxTime: (input.id === 'timeFrom' ?
		$('#timeTo').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:  

 

 

 

 

 

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('option',
			{spinnerBigImage: (expanded ? 'img/' + this.id + 'Big.png' : '')});
	});
});

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

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 many of them inline in the data-timeEntry attribute.

Inline configuration 1:

Inline configuration 2:

<input type="text" size="10" class="inlineConfig"
	data-timeEntry="show24Hours: true, timeSteps: [1, 30, 0], appendText: ' (see below)'">
	
<input type="text" size="10" class="inlineConfig"
	data-timeEntry="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:

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

$('#switchButton').click(function() {
	var show24Hours = $('#reConfig').timeEntry('option', 'show24Hours');
	$('#reConfig').timeEntry('option', 
		{show24Hours: !show24Hours, showSeconds: show24Hours});
});
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.

:

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

And then configure the language per time entry field.

$('#l10nTime').timeEntry($.timeEntry.regionalOptions['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 (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).timeEntry({
	show24Hours: false, // True to use 24 hour time, false for 12 hour (AM/PM)
	unlimitedHours: false, // True to allow entry of more than 24 hours, false to restrict to one day
	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: null, // The field to highlight initially,
		// 0 = hours, 1 = minutes, ..., or null for user selection
	noSeparatorEntry: false, // True to move to next sub-field after two digits entry
	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
	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.regionalOptions[] // Language/country-specific localisations

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

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

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

$(selector).timeEntry('getOffset') // Retrieve the current time offset