jQuery Time Entry Reference

A jQuery plugin that sets an input field up to accept a time value. 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.4.9. See a demonstration of the time entry plugin and download the code from there. Or see a minimal page that you could use as a basis for your own investigations.

Instance Settings

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

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

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="{show24Hours: true}"/>

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

ampmNames | ampmPrefix | appendText | beforeSetTime | beforeShow | defaultTime | initialField | maxTime | minTime | separator | show24Hours | showSeconds | spinnerBigImage | spinnerBigSize | spinnerImage | spinnerIncDecOnly | spinnerRepeat | spinnerSize | spinnerTexts | timeSteps | useMouseWheel

NameTypeDefaultComments
show24Hoursbooleanfalse Indicate whether to use 12-hour (false) or 24-hour (true) time. This is one of the regional settings fields.
showSecondsbooleanfalse Indicate whether or not the seconds part of the time should be displayed.
separatorstring':' The separator between time portions. This is one of the regional settings fields.
ampmPrefixstring'' The text that separates the time from the AM and PM indicators. This is one of the regional settings fields.
ampmNamesstring[2]['AM', 'PM'] The AM and PM display text. This is one of the regional settings fields.
appendTextstring'' Add content to display after each time field. This may contain HTML markup.
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. [1, 15, 0] restricts the times to quarter hours.
initialFieldnumber0 The number of the portion of the time field to highlight initially. Use 0 for hours, 1 for minutes, etc.

Since 1.3.0.
useMouseWheelbooleantrue True to use the mouse wheel for increment/decrement if possible, false to never use it.
defaultTimeDate or number or stringnull The default time to show when no other value has been entered. This may be a Date object (but the year/month/day values are ignored), a string in the current time format, a numeric value as seconds offset from now, or a string value indicating a number and units, e.g. '+2h'. In the latter case, use '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. '-2h -20m'. Prefix with '!' to prevent a wrap around into another day. Leave as null to default to the current time.

$(selector).timeEntry({defaultTime: new Date(0, 0, 0, 11, 30, 0)});
$(selector).timeEntry({defaultTime: '11:30AM'});
$(selector).timeEntry({defaultTime: +20});
$(selector).timeEntry({defaultTime: '!+2h +30m'});

Since 1.3.1 - for relative settings.
Since 1.4.8 - as a string in time format.
minTimeDate or number or stringnull The minimum time that may be selected, or null for no limit. See defaultTime for a description of the possible formats.

$(selector).timeEntry({minTime: new Date(0, 0, 0, 8, 30, 0)});
$(selector).timeEntry({minTime: '08:30AM'});
$(selector).timeEntry({minTime: -15});
$(selector).timeEntry({minTime: '-1h -10m'});

Since 1.3.1 - for relative settings.
Since 1.4.8 - as a string in time format.
maxTimeDate or number or stringnull The maximum time that may be selected, or null for no limit. See defaultTime for a description of the possible formats.

$(selector).timeEntry({maxTime: new Date(0, 0, 0, 17, 30, 0)});
$(selector).timeEntry({maxTime: '05:30PM'});
$(selector).timeEntry({maxTime: +30});
$(selector).timeEntry({maxTime: '+20m +10s'});

Since 1.3.1 - for relative settings.
Since 1.4.8 - as a string in time format.
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 time, 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.

Since 1.4.3.
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 time, or 0 for no central button.

Since 1.4.3.
spinnerIncDecOnlybooleanfalse True to have only the increment and decrement buttons on the spinner, or false for all the buttons.
spinnerTextsstring[5] ['Now', '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 time entry for this field. For example, you can use it to set up a 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).timeEntry({beforeShow: customRange});

function customRange(input) {
	return {minTime: (input.id == 'tTo' ?
		$('#tFrom').timeEntry('getTime') : null), 
		maxTime: (input.id == 'tFrom' ?
		$('#tTo').timeEntry('getTime') : null)};
}
beforeSetTimefunctionnull A function that accepts the old and new times, and minimum and maximum times, and returns an updated time. this refers to the associated input field. This call is made just before the time is updated into the field allowing for additional restrictions to be applied. Leave as null for no additional restrictions.

$(selector).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;
}

Since 1.4.0.

Global Settings

NameTypeDefaultComments
regionalobject[] The set of regional settings for the 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: show24Hours, separator, ampmPrefix, ampmNames, spinnerTexts. Language packages load new entries into this array and automatically apply them as global defaults.

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

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

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

and apply the language settings to individual fields with

$('#frenchTime').timeEntry($.timeEntry.regional['fr']);

Check out the list of available localisation packages.

Functions

change | destroy | disable | enable | getOffset | getTime | isDisabled | setDefaults | setTime

SignatureReturnsComments
$.timeEntry.setDefaults(settings)- Update the default instance settings to use with all time entry instances.

$.timeEntry.setDefaults({show24Hours: true, showSeconds: true});
$(selector).timeEntry('change', settings)jQuery Update the settings for the time entry instance(s) attached to the given input field(s).

$(selector).timeEntry('change', {show24Hours: true, showSeconds: true});
$(selector).timeEntry('change', name, value)jQuery Update a single setting for the time entry instance(s) attached to the given input field(s).

$(selector).timeEntry('change', 'show24Hours', true);

Since 1.4.8.
$(selector).timeEntry('destroy')jQuery Remove the time entry functionality from the given input field(s).
$(selector).timeEntry('disable')jQuery Disable the given input field and any spinner attached to it, preventing it from being used for time entry.
$(selector).timeEntry('enable')jQuery Enable the given input field and any spinner attached to it, allowing it to be used for time entry.
$(selector).timeEntry('isDisabled')boolean Determine whether the (first) given input field has been disabled (true).
$(selector).timeEntry('setTime', time)jQuery Update and display the time in the correct format for the given input field(s). See defaultTime for a description of the possible formats for time. Use 0 for the current time. Use null or '' to clear the time.

$(selector).timeEntry('setTime', new Date(0, 0, 0, 8, 30, 0));
$(selector).timeEntry('setTime', '11:30AM');
$(selector).timeEntry('setTime', +20);
$(selector).timeEntry('setTime', '+2h +30m');

Since 1.3.1 - for relative settings.
Since 1.4.8 - as a string in time format.
Since 1.4.9 - null or '' clears the time.
$(selector).timeEntry('getTime')Date Retrieve the time for the (first) given input field as a Date object with the year/month/day values set to zero. Returns null if the field is blank.
$(selector).timeEntry('getOffset')number Retrieve the 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).timeEntry('getOffset'));

Since 1.4.8.

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

Valid HTML 4.01 Strict