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.7. 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.

Settings
Global

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.

Name	Type	Default	Comments
show24Hours	boolean	false	Indicate whether to use 12-hour (false) or 24-hour (true) time. This is one of the regional settings fields.
showSeconds	boolean	false	Indicate whether or not the seconds part of the time should be displayed.
separator	string	':'	The separator between time portions. This is one of the regional settings fields.
ampmPrefix	string	''	The text that separates the time from the AM and PM indicators. This is one of the regional settings fields.
ampmNames	string[2]	['AM', 'PM']	The AM and PM display text. This is one of the regional settings fields.
appendText	string	''	Add content to display after each time field. This may contain HTML markup.
timeSteps	number[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.
initialField	number	0	The number of the portion of the time field to highlight initially. Use 0 for hours, 1 for minutes, etc. Since 1.3.0.
useMouseWheel	boolean	true	True to use the mouse wheel for increment/decrement if possible, false to never use it.
defaultTime	Date or number or string	null	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 numeric value (seconds from now, e.g. +300), 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. Since 1.3.1.
minTime	Date or number or string	null	The minimum time that may be selected, or `null` for no limit. See `defaultTime` for a description of the possible formats. Since 1.3.1 - for relative settings.
maxTime	Date or number or string	null	The maximum time that may be selected, or `null` for no limit. See `defaultTime` for a description of the possible formats. Since 1.3.1 - for relative settings.
spinnerImage	string	'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.
spinnerSize	number[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.
spinnerBigImage	string	''	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.
spinnerBigSize	number[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.
spinnerIncDecOnly	boolean	false	True to have only the increment and decrement buttons on the spinner, or false for all the buttons.
spinnerTexts	string[5]	['Now', 'Previous field', 'Next field', 'Increment', 'Decrement']	The tooltip text for the spinner buttons. This is one of the regional settings fields.
spinnerRepeat	number[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.
beforeShow	function	null	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.
beforeSetTime	function	null	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. Since 1.4.0.

Global Settings

Name	Type	Default	Comments
regional	object[]		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

Signature	Returns	Comments
$.timeEntry.setDefaults(settings)	-	Update the default instance settings (see above) to use with all time entry instances.
$(inputs).timeEntry('change', settings)	jQuery	Update the settings for the time entry instance(s) attached to the given input field(s).
$(inputs).timeEntry('destroy')	jQuery	Remove the time entry functionality from the given input field(s).
$(inputs).timeEntry('disable')	jQuery	Disable the given input field and any spinner attached to it, preventing it from being used for time entry.
$(inputs).timeEntry('enable')	jQuery	Enable the given input field and any spinner attached to it, allowing it to be used for time entry.
$(inputs).timeEntry('isDisabled')	boolean	Determine whether the (first) given input field has been disabled (true).
$(inputs).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 `null` for the current time. Since 1.3.1 - for relative settings.
$(inputs).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.