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 adding them to the data-timeEntry attribute (provided they are simple values or arrays), e.g.

<input type="text" data-timeEntry="show24Hours: true, minTime: 'new Date(0, 0, 0, 8, 30, 0)'"/>

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 | noSeparatorEntry | separator | show24Hours | showSeconds | spinnerBigImage | spinnerBigSize | spinnerImage | spinnerIncDecOnly | spinnerRepeat | spinnerSize | spinnerTexts | tabToExit | timeSteps | unlimitedHours | 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.
unlimitedHoursbooleanfalse Indicate whether to restrict hours to just those in one day (false) or to allow for any value for hours (true).

Since 2.0.1.
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.
initialFieldnumbernull The number of the portion of the time field to highlight initially. Use 0 for hours, 1 for minutes, etc., or null for the user selection.

Since 1.3.0.
Since 2.0.0 - default is now null.
noSeparatorEntrybooleanfalse Set to true to allow direct entry of a time from the keyboard without needing to type separators, i.e. the field moves on after two digits.

Since 1.5.0.
tabToExitbooleanfalse true to have the tab key exit this field and move to the next one, or false to have the tab key step through the date subfields.

Since 2.0.0.
useMouseWheelbooleantrue Set to true to use the mouse wheel for increment/decrement if possible, or 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 string or number[]null The minimum time that may be selected, or null for no limit. See defaultTime for a description of the possible formats. Use an array of number for hours, minutes, seconds in conjunction with unlimitedHours.

$(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.
Since 2.0.1 - may be number array for unlimited hours.
maxTimeDate or number or string or number[]null The maximum time that may be selected, or null for no limit. See defaultTime for a description of the possible formats. Use an array of number for hours, minutes, seconds in conjunction with unlimitedHours.

Note that the maxTime may be set to less than the minTime in which case the entered time is restricted to the period between the minimum and the maximum on the "next day".

$(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.
Since 1.5.2 - overnight range.
Since 2.0.1 - may be number array for unlimited hours.
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 Set to 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
regionalOptionsobject[] 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.regionalOptions['']);

and apply the language settings to individual fields with

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

Check out the list of available localisation packages.

Since 2.0.0 - previously called regional.

Functions

destroy | disable | enable | getOffset | getTime | isDisabled | option (get) | option (set) | 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('option', options)jQuery object Update the settings for the time entry instance(s) attached to the given input field(s).

options (object) the collection of new settings.

$(selector).timeEntry('option', {show24Hours: true, showSeconds: true});

Since 1.5.0 - previously you used the 'change' command.
$(selector).timeEntry('option', name, value)jQuery object Update a particular setting for the time entry instance(s) attached to the given input field(s).

name (string) the name of the setting to change;
value (any) the new value of that setting.

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

Since 1.4.8.
Since 1.5.0 - previously you used the 'change' command.
$(selector).timeEntry('option', name)object or any Retrieve one or all of the current settings for the first time entry instance attached to the given input field(s).

name (string, optional) the name of the setting to retrieve; omit for all settings.

var settings = $(selector).timeEntry('option');
var show24Hours = $(selector).timeEntry('option', 'show24Hours');

Since 1.5.0.
$(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(2014, 1-1, 26);
dt.setTime(dt.getTime() + $(selector).timeEntry('getOffset'));

Since 1.4.8.