Intimidatetime - jQuery and Zepto datetime picker

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

Github

Version

Version 0.2.0

Last updated on 2014-07-08

License

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

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.

var $basicEx4 = $('#ex_basic_4').intimidatetime({
	buttons: [
			{ 
				text: 'Done', 
				action: function(e){ $basicEx4.intimidatetime('close'); return false; } 
			},
			{ 
				text: 'Now', 
				action: function(e){ $basicEx4.intimidatetime('value', new Date() ); return false; }
			}
		]
});

You can change input types using the units.{unit type}.type option.

$('#ex_basic_5').intimidatetime({
	format: 'MMM yyyy',
	units: {
		year: { type: 'list', options: [2013,2014,2015] },
		month: { type: 'list', format: 'MMMM' }
	}
});

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: ', '
});

Intimidatetime Date Time Picker for jQuery and Zepto