Intimidatetime Date Time Picker for jQuery and Zepto

Introduction

Intimidatetime is a wicked awesome date time picker for both jQuery and Zepto. It features high customization with low configuration. Features include date ranges, unix timestamps, timezones, date utility methods, and more.

The name itself is a play on words "intimidate" and "datetime". Merged together we get IntimiDateTime, since the only real way to wrestle with time is to intimidate time!

Get Started

Highly Recommended

Subscribe to my newsletter and follow me @practicalweb.

eBook: Handling Time

Learn about basic setup, i18n, timezones, and storing dates and times in a database. eBook examples use jQueryUI Timepicker Addon, however the principles learned are the same.

buy eBook + Example code

buy eBook

Donation

Has Intimidatetime been helpful to you?

Download

Version

Version 0.1.0

Last updated on 2013-10-26

License

Intimidatetime is currently available for use in all personal or commercial projects under the MIT license.

Options

Options are subject to change. Also visit the I18n for additional options:

{

	// Date object, array of Date objects, or strict formatted string to set as the value
	value: null,

	// picker time format
	previewFormat: null,

	// format shown in the alt field if used, defaults to format option
	altFormat: null,

	// jQuery element or selector for an alternate input
	alt: null,

	// min allowed date - date object or relative string '-1M'
	min: null,

	// max allowed date - date object or relative string '-1M'
	max: null,

	// number of ranges or pick list of dates, will generate a calendar side by side for each date
	ranges: 0,

	// string to delimit ranges. this string MUST NOT occur in the time format
	rangeDelimiter: ' - ',

	// relative date string for the minimum allowed difference between two dates
	rangeIntervalMin: '+0l',

	// relative date string for the maximum allowed difference between two dates
	rangeIntervalMax: null,

	// number of months to show at once
	months: 1,

	// 0-6, which day is the start of the week
	startOfWeek: 0,

	// whether the picker should be inline
	inline: false,

	// use theme to prefix all class names, change your css accordingly
	theme: 'intimidatetime',

	// how the picker is aligned: vertical, horizontal (maps to css styling, no logic). Or should this be "classes"?
	mode: 'basic',

	// define any and all units
	units: {
		year: { map: 'FullYear', type: 'select', range: 20, step: 1, format: 'yyyy', value: null},
		month: { map: 'Month', type: 'select', min: 0, max: 11, step: 1, format: 'MMM', value: null },
		day: { map: 'Date', type: 'select', min: 1, max: 31, step: 1, value: null },
		hour: { map: 'Hours', type: 'select', min: 0, max: 23, step: 1, value: null },
		minute: { map: 'Minutes', type: 'select', min: 0, max: 59, step: 1, value: null },
		second: { map: 'Seconds', type: 'select', min: 0, max: 59, step: 1, value: null },
		milli: { map: 'Milliseconds', type: 'select', min: 0, max: 999, step: 10, value: null },
		micro: { map: 'Microseconds', type: 'select', min: 0, max: 999, step: 10, value: null },
		timezone: { map: 'Timezone', type: 'select', value: null, options: [720,660,600,570,540,480,420,360,300,270,240,210,180,120,60, // just like Date.getTimezoneOffset()
				0,-60,-120,-180,-210,-240,-270,-300,-330,-345,-360,-390,-420,-480,-525,-540,-570,-600,-630,-660,-690,-720,-765,-780,-840],
				names: {} // Key value pairs mapping timezone values to text values { "-240": "EDT", "-300": "CDT".. }
			}
	},

	// the order which each module appears
	groups: [
		{ name: 'date', units: ['year', 'month', 'day'] },
		{ name: 'time', units: ['hour', 'minute', 'second', 'millisecond', 'microsecond', 'timezone'] }
	],

	// buttons can be added at the bottom of the picker
	buttons: [
		//{ text: 'Done', classes: '', tag: 'button', action: function(inst){} }
	],

	events: {
		// event fired on value change request, use event.preventDefault() or return false to prevent value change
		change: function(e, date, inst){},

		// event fired when the picker is (re)built
		refresh: function(e, inst){},

		// event fired to validate a day, use event.preventDefault() or return false to disable the day
		enableDay: function(e, date, inst){},

		// event fired when the picker is opened, use event.preventDefault() or return false to prevent opening
		open: function(e, inst){},

		// event fired when the picker is closed, use event.preventDefault() or return false to prevent closing
		close: function(e, inst){}
	}
}

Methods

Instance Methods

Instance methods are available through the intimidatetime jQuery plugin. Calling these methods resemble:

var myPicker = $('.selector').intimidatetime();
mypicker.intimidatetime('open'); // open the picker

The following instance methods are currently available:

.intimidatetime('enable')

Enables the intimidatetime picker.

return
jQuery element
.intimidatetime('disable')

Disables the intimidatetime picker.

return
jQuery element
.intimidatetime('destroy')

Disables and removes the intimidatetime picker.

return
jQuery element
.intimidatetime('open')

Opens the picker manually.

return
jQuery element
.intimidatetime('close')

Closes the picker manually.

return
jQuery element
.intimidatetime('option', 'key', 'value')

Gets or sets an option.

key
String of the option value to get or set
value
(optional) Value to set the option to.
return
When setting the jQuery element. When getting returns the option's value.
.intimidatetime('value', val)

Gets or sets the picker's value.

value
(optional) A Date object, or when using ranges and array of Date objects
return
When setting the jQuery element. When getting returns the value (single Date or array of Dates when using ranges).
.intimidatetime('refresh')

Rebuilds the picker.

return
jQuery element

Utility Methods

Utility/Static Methods are available through the $.intimidatetime object, so calling them resembles:

var num = $.intimidatetime.daysInMonth(5, 2001);

The following utility methods are available:

setDefaults(options)

Sets the defaults for intimidatetime instances

options
object of intimidatetime options
return
$.intimidatetime object
dateClone(date)

Creates a clone of a date, with Intimidatetime's microsecond and timezone support.

date
Javascript Date object to clone
return
A new javascript Date object with the same value as requested
dateParse(date, format, options)

Parse a date string with the specified format

date
A date string
format
A format string (see formatting options)
options
Object of option values (see options and i18n)
return
A javascript Date object
dateRangeParse(dates, format, delimiter, options)

Parse a date string of date ranges with the specified format, dates split by delimiter

dates
A string dates
format
A format string for a single date(see formatting options)
delimiter
A string that delimits each date.
options
Object of option values (see options and i18n)
return
Array of javascript Date objects
dateRelative(date, relative)

Compute and return a new date relative to the given one.

date
A javascript Date to base the calculation from
relative
A string with a date calclulation (ex: "+2y", "-1M+5d"). Use a +/- followed by the number of units followed by the unit (y=year, M=month, d=day, h=hour, m=minute, s=second, l=millisecond, c=microsecond).
return
A javascript Date object of the new date value.
dateFormat(date, format, options)

Format a Date object to the given format

date
A javascript Date object
format
A format string (see formatting options)
options
Object of option values (see options and i18n)
return
A string of the formattd date
dateRangeFormat: function(dates, format, delimiter, options)

Format an array of dates into a date range string with the specified format, dates split by delimiter

dates
A array of Javascript Date objects
format
A format string for a single date(see formatting options)
delimiter
A string that delimits each date.
options
Object of option values (see options and i18n)
return
A string of formatted dates
timezoneOffsetNumber(tzString, lookup)

Compute the number of minutes offset for a timezone string (ex: "-0400" gives 240)

tzString
A timezone string (ex: "-0400" or "Z" for iso1806
lookup
Object of timezone translation key value pairs. When the tzString isn't directly computable it will try to lookup the string. For example if you pass "EST" it may not be directly computable, if the lookup contains { "260": "EST" } it can return a value. See timezone names in Options.
return
Number of minutes needed to return to GMT
daysInMonth(m, y)

Compute the number of days in a month

m
A number indicating the month. 0=January, 11=December, just like a javascript Date.
y
A number indicating the year.
return
Number of days in the month
detectSupport(timeFormat)

Scan a timeFormat string and determine what features should be supported.

timeFormat
A string containing format tokens
return
An object of boolean values of each supported feature.
log([])

Log to the console, when available any number of arguments

args
Any number of arguments of any type
return
Void

Events

Events may be passed through the options (see Options for avaible events) or you can bind to them manually:

var myPicker = $('.selector').intimidatetime();

myPicker.on('intimidatetime:change', function(e, date, inst){
	console.log('Time Changed!');
});

Notice the "intimidatetime:" indicates the namespace for the events, then the event name.

Formatting

Formatting your date/time uses special tokens inside a string. The following are the tokens allowed and their meaning.

u
Unix timestamp (seconds)
yy
Two digit year
yyyy
Four digit year
M
Month with no leading 0
MM
Month with leading 0
MMM
Month name abbreviation as defined in i18n
MMMM
Month name as defined in i18n
d
Day with no leading 0
dd
Day with leading 0
ddd
Day name abbreviation as defined in i18n
dddd
Day name as defined in i18n
HH
Hour with leading 0 (24 hour)
h
Hour with no leading 0 (12 hour)
hh
Hour with leading 0 (12 hour)
m
Minute with no leading 0
mm
Minute with leading 0
s
Second with no leading 0
ss
Second with leading 0
l
Milliseconds always with leading 0
c
Microseconds always with leading 0
t
a or p for AM/PM
T
A or P for AM/PM
tt
am or pm for AM/PM
TT
AM or PM for AM/PM
z
Timezone as defined by timezoneList
zz
Timezone as defined by timezoneList, but in Iso 8601 format (+04:45)
zzz
Timezone as defined by i18n timezone names. (You must define these)
'...'
Literal text (Uses single quotes)

Internationalization (i18n)

Intimidate time comes with full support for i18n. You can create your own or use the pre-built ones in the i18n directory by simply including it in your page.

$.intimidatetime.i18n['en'] = {
	format: 'yyyy-MM-dd HH:mm',      // default format 'yyyy-MM-dd hh:mm:ss:l tt z'
	units: {
		year: { 
				format: 'yyyy',      // how should hour be forrmated in drowdown
				label: 'Year'        // year label
			},
		month: { 
				format: 'MMM',       // how should hour be forrmated in drowdown
				label: 'Month',      // month label
				names: ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'], 
				namesAbbr: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
			},
		day: { 
				format: 'd',         // how should hour be forrmated in drowdown 
				label: 'Day',        // day label
				names: ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'],
				namesAbbr: ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'],
				namesHead: ['Su', 'Mo', 'Tu', 'We', 'Th', 'Fr', 'Sa']
			},
		hour: {  
				format: 'HH',        // how should hour be forrmated in drowdown
				label: 'Hour',       // hour label
				am: ['AM', 'A'],     // possible am names
				pm: ['PM', 'P']     // possible pm names
			},
		minute: { 
				format: 'mm',        // how should minute be formatted in dropdown
				label: 'Minute'      // minute label
			},
		second: { 
				format: 'ss',        // how should second be formatted in dropdown
				label: 'Second'      // second label
			},
		millisecond: { 
				format: 'l',         // how should millisecond be formatted in dropdown
				label: 'Millisecond' // millisecond label
			},
		microsecond: { 
				format: 'c',         // how should millisecond be formatted in dropdown
				label: 'Microsecond' // microsecond label
			},
		timezone: { 
				format: 'z',         // how should timezone be formatted in dropdown
				label: 'Timezone'    // minute label
			}
	},
	rtl: false
};
$.intimidatetime.setDefaults($.intimidatetime.i18n['en']);

Examples

Basics

A timepicker in the simplest fashion.

$('#ex_basic_1').intimidatetime();

Add a few options, change the format. Intimidate time detects which time units are needed by the format.

$('#ex_basic_2').intimidatetime({
	format: 'MMM d, yyyy'
});

Use the preview format, this is useful when you need to generate a Unix timestamp.

$('#ex_basic_3').intimidatetime({
	format: 'u',
	previewFormat: 'yyyy-MM-dd HH:mm:ss'
});

You can add on extra functionality by using buttons. Pass an array of as many as you like.

$('#ex_basic_4').intimidatetime({
	buttons: [
			{ text: 'Done', action: function(inst){ inst.close(); } },
			{ text: 'Now', action: function(inst){ inst.value( new Date() ); } }
		]
});

Timezones

You can enable timezones with the "z" format token.

$('#ex_timezone_1').intimidatetime({
	format: 'yyyy-MM-dd HH:mm z'
});

Suppose you want the user to have more readable timezone descriptions, but behind the scenes Intimidate time needs the numeric timezone. We can pass a few timezone options.

The option values must be minute offsets from utc. Just like Date.getTimezoneOffset() the offset for -0400 is 240. Intimidatetime tries to follow the path laid by javascript. Then You can assign names to each value.

$('#ex_timezone_2').intimidatetime({
	format: 'yyyy-MM-dd HH:mm zzz',
	units: {
		timezone: {
			format: 'zzz',
			options: [240,300,360,420],
			names: {
				"240": "EDT", 
				"300": "CDT", 
				"360": "MDT",
				"420": "PDT"
			}
		}
	}
});

Ranges

Ranges are very simple, just use the range option.

$('#ex_ranges_1').intimidatetime({
	ranges: 1
});

Sometimes maybe you don't want a range necessarily, but a list of dates. Use the rangeDelimiter and range options together. Here we request 3 dates.

$('#ex_ranges_2').intimidatetime({
	format: 'yyyy-MM-dd',
	ranges: 2,
	rangeDelimiter: ', '
});