A jQueryplugin
that sets an input field up to accept a date and/or time value using a spinner.
For date entry via a popup calendar, use the jQuery Datepicker plugin.
For support of other world calendars, and a datepicker that works with them,
see the jQuery Calendars plugin.
This plugin combines the jQuery Date Entry and
jQuery Time Entry plugins and will replace them.
The current version is 2.0.0 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 date/time entry functionality can easily be added to an input field
with appropriate default settings. Also shown is the control's
appearance when disabled.
Processed fields are marked with a class of is-datetimeEntry
and are not re-processed if targeted a second time.
A note on Date - the JavaScript Date constructor expects
the year, month, and day as parameters. However, the month ranges from 0 to 11.
To make explicit what date is intended (does a month of 3 mean March or April?)
I specify the month from 1 to 12 and manually subtract the 1.
Thus the following denotes 25 December, 2010.
$(selector).datetimeEntry({minDatetime: new Date(2010, 12-1, 25)});
Keystrokes
The date/time entry field also responds to keystrokes.
You may also specify alternate separators for keyed entry.
In this case you can also use '.' or '-'.
down/updecrement/increment current date/time portion
left/rightmove to previous/next date/time portion
shift+/tabmove to previous/next date/time portion
(unless flagged to exit)
home/endmove to the first/last date/time portion
ctrl+homeset to the current date/time
ctrl+end or deleteclear the date/time
Date/Time Formats
You can control how the date/time is presented. The datetimeFormat
setting consists of a sequence of characters indicating the order of the fields
and any separators. Use 'y' for two-digit year, 'Y' for four-digit-year, 'o' for month,
'O' two-digit month, 'n' for abbreviated month name, 'N' for full month name,
'd' for day, 'D' two-digit day, 'w' for abbreviated day of the week and day,
'W' for full day of the week and day, 'h' for hours, 'H' two-digit hours,
'm' for minutes, 'M' two-digit minutes, 's' for seconds, 'S' two-digit seconds,
or 'a' for AM/PM. Hours are displayed in 24-hour time if no AM/PM field is included.
When setting the date/time you can provide a Date object, or a number
of seconds from now, or a string containing the period and units:
'y' for years, 'o' for months, 'w' for weeks, 'd' for days, '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.
function getTheDateTime() {
alert('The date/time is ' + $('#' + $('#pickInput').val()).
datetimeEntry('getDatetime'));
}
function setTheDateTime() {
var date = ($('#abs').is(':checked') ?
new Date(2014, 1 - 1, 26, 11, 30) : '+1o +1w +10h');
$('#' + $('#pickInput').val()).datetimeEntry('setDatetime', date);
}
$('#getTheDateTime').click(getTheDateTime);
$('#setTheDateTime').click(setTheDateTime);
Date/Time Restrictions
You can restrict the functionality of the date/time entry fields in various ways.
Such as limiting the range of dates and/or times selectable within the field.
Or you can constrain the time increments, for example to only the quarter hours.
Limited date/times:
$('#restrictRange').datetimeEntry({minDatetime: new Date(2013, 10 - 1, 4, 9, 0, 0),
maxDatetime: new Date(2013, 10 - 1, 8, 17, 30, 0)});
Limited time range only:
$('#restrictTimes').datetimeEntry({minTime: new Date(0, 0, 0, 9, 0, 0),
maxTime: new Date(0, 0, 0, 17, 30, 0)});
The range of selectable dates/times can also be set as relative to the current date/time.
Use a number for seconds from now, or a string containing the period and units:
'y' for years, 'o' for months, 'w' for weeks, 'd' for days, '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.
You can set an alternate field to be kept synchronised with the date/time entry field,
and it may have a different format. Use this to display more user-friendly text
while passing a more easily used format to the server.
Alternate field:
$('#withAlternate').datetimeEntry({datetimeFormat: 'w n Y H:Ma',
altField: '#alternateField', altFormat: 'Y-O-DTH:M:S'});
You can set which portion of the date/time should be initially highlighted.
Alternatively, the default date/time can be set relative to the current date/time.
Use a number for seconds from now, or a string containing the period and units:
'y' for years, 'o' for months, 'w' for weeks, 'd' for days, '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.
Use a custom field settings function to create a date/time range control:
two date/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 date/time entry fields via parameters to the instantiation call,
you can specify many of them inline in the data-datetimeEntry attribute.
You can localise the date/time entry fields for other languages and regional differences.
The date/time entry defaults to English with a date/time format of mm/dd/yyyy hh:mmap.
Select a language to change the date/time format and spinner tooltips.
:
You need to load the appropriate language package (see list below), which
adds a language set ($.datetimeEntry.regionalOptions[langCode]) and automatically
sets this language as the default for all date/time entry fields.
And then configure the language per date/time entry field.
$('#l10nDatetime').datetimeEntry($.datetimeEntry.regionalOptions['fr']);
$('#l10n2Datetime').datetimeEntry($.extend({},
$.datetimeEntry.regionalOptions['fr'], {datetimeFormat: 'w n Y H:Ma'}));
$('#l10n3Datetime').datetimeEntry($.extend({},
$.datetimeEntry.regionalOptions['fr'], {datetimeFormat: 'W N Y H:Ma'}));
$('#language').change(localise);
In the Wild
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).datetimeEntry({
datetimeFormat: 'O/D/Y H:Ma', // The format of the date text:
// 'y' for short year, 'Y' for full year, 'o' for month, 'O' for two-digit month,
// 'n' for abbreviated month name, 'N' for full month name,
// 'd' for day, 'D' for two-digit day, 'w' for abbreviated day name and number,
// 'W' for full day name and number), 'h' for hour, 'H' for two-digit hour,
// 'm' for minute, 'M' for two-digit minutes, 's' for seconds,
// 'S' for two-digit seconds, 'a' for AM/PM indicator (omit for 24-hour)
datetimeSeparators: '.', // Additional separators between datetime portions
monthNames: ['January', 'February', 'March', 'April', 'May', 'June',
'July', 'August', 'September', 'October', 'November', 'December'], // Names of the months
monthNamesShort: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'], // Abbreviated names of the months
// Names of the days
dayNames: ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'],
dayNamesShort: ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'], // Abbreviated names of the days
ampmNames: ['AM', 'PM'], // Names of morning/evening markers
// The popup texts for the spinner image areas
spinnerTexts: ['Today', 'Previous field', 'Next field', 'Increment', 'Decrement'],
appendText: '', // Display text following the input box, e.g. showing the format
initialField: null, // The field to highlight initially,
// use 0 for the first field, or null for user selection
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
shortYearCutoff: '+10', // The century cutoff for two-digit years,
// absolute (numeric) or relative (string)
defaultDatetime: null, // The date to use if none has been set, leave at null for now
minDatetime: null, // The earliest selectable datetime, or null for no limit
maxDatetime: null, // The latest selectable datetime, or null for no limit
minTime: null, // The earliest selectable time regardless of date, or null for no limit
maxTime: null, // The latest selectable time regardless of date, or null for no limit
timeSteps: [1, 1, 1], // Steps for each of hours/minutes/seconds when incrementing/decrementing
spinnerImage: 'spinnerDefault.png', // The URL of the images to use for the date 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 date
spinnerBigImage: '', // The URL of the images to use for the expanded date 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 date
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 date entry
altField: null, // Selector, element or jQuery object for an alternate field to keep synchronised
altFormat: null // A separate format for the alternate field
});
$.datetimeEntry.regionalOptions[] // Language/country-specific localisations
$.datetimeEntry.setDefaults(settings) // Set default values for all instances
$(selector).datetimeEntry('option', settings) // Change the settings for selected instances
$(selector).datetimeEntry('option', name, value) // Change a single setting for selected instances
$(selector).datetimeEntry('option', name) // Retrieve a setting value
$(selector).datetimeEntry('destroy') // Remove the date entry functionality
$(selector).datetimeEntry('disable') // Disable date entry
$(selector).datetimeEntry('enable') // Enable date entry
$(selector).datetimeEntry('isDisabled') // Determine if field is disabled
$(selector).datetimeEntry('setDatetime', datetime) // Set the date/time for the instance
$(selector).datetimeEntry('getDatetime') // Retrieve the currently selected date/time
$(selector).datetimeEntry('getOffset') // Retrieve time only 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 date entry code. These packages
automatically apply their settings as global default values.