A jQueryplugin
that sets an input field up to pick a time value using a spinner.
Complement this plugin with the jQuery Datepicker
plugin, for a popup calendar, the jQuery Calendars plugin,
for support of other world calendars and a datepicker that works with them, or the
jQuery Date Entry plugin, for spinner entry of dates, or
combine date and time entry with the jQuery Date/Time Entry plugin.
The current version is 2.0.1 and is available
under the MIT licence.
For more detail see the documentation reference page.
Or see a minimal page that you could
use as a basis for your own investigations.
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.
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.
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.
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.
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.
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.
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.
Instead of configuring time entry fields via parameters to the instantiation call,
you can specify many of them inline in the data-timeEntry attribute.
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.
This tab highlights examples of this plugin in use "in the wild".
None as yet.
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
Usage
Include the jQuery library (1.7+) in the head section of your page.
Localisation packages are available for download and
should be loaded after the main time entry code. These packages
automatically apply their settings as global default values.