Matt Snider JavaScript Resource

Like String, the native JavaScript Date object also does not have as many helper functions as you might like. Using a similar approach as we did with String, we can attach additional functionality to Date.

Example 1: Date Augmentation

YAHOO.lang.augmentObject(Date, {

	/**
	 * Date constant for full month names
	 *
	 * @property MONTHS
	 * @type string
	 */
	MONTHS: [’January’,'February’,'March’,'April’,'May’,'June’,'July’,'August’,'September’,'October’,'November’,'December’],

	/**
	 * Returns a date object from the string; expects ‘MonthName, DayNr Year Hrs:Min:Sec’, may not work properly on other strings in all browsers
	 *
	 * @method getDate
	 * @param s {string} the date as a string
	 * @return {date} a date object, defined by the passed string
	 * @static
	 */
	getDate: function(s) {
		var d = new Date();
		d.setTime(Date.parse(s));
		return d;
	}
}, true);

I try to only attach constants and static methods to the JavaScript Native Object (Date) itself. Dynamic objects/methods should be attached to the prototype of the Object (Date.prototype) so that all instantiations of that Date have access to them. In example 1, we attach a constant array (the full American month names) and one method ‘getDate’ (retrieves the date from a string). The constants can be used to retrieve the month name for a date, a feature that is missing from JavaScript, most likely because of localization concerns. ‘getDate’ is a nice shortcut, when you have a date string (say from an AJAX request) and need to convert it to a Date object for manipulation.

Example 2: Date.prototype Augmentation

//  Extending the Date.prototype Object

YAHOO.lang.augmentObject(Date.prototype, {

	/**
	 * Retrieves the name of the month
	 *
	 * @method getMonthName
	 * @return {string} the month name
	 * @public
	 */
	getMonthName: function() {
		return Date.MONTHS[this.getMonth()];
	},

	/**
	 * Retrieves the abbreviated name of the month
	 *
	 * @method getMonthNameAbbr
	 * @return {string} the abbreviated month name
	 * @public
	 */
	getMonthNameAbbr: function() {
		return this.getMonthName().substr(0,3);
	},

	/**
	 * Converts the JavaScript Date into a date string. Recognizes the following format characters: y = year, m = month, d = day of month, h = hour, i = minute, s = second
	 *
	 * @method toDateString
	 * @param (string} format OPTIONAL: The string format to convert the JavaScript Date into (ie. ‘m/d/y’ or ‘m. d, y’); default is ‘m/d/y’
	 * @param {boolean} showZeros OPTIONAL: Forces trailing zeros, so 9/1/2006 becomes 09/01/2006
	 * @param {Mixed} useMonthName OPTIONAL: string or boolean, use the month name instead of the digit, (’abbr’ uses the short name)
	 * @return {string} the JavaScript Date as a string
	 * @public
	 */
	toDateString: function(format, showZeros, useMonthName) {
		if (! isType(format, ’string’)) {format = ‘m/d/y’;}
		format = format.toLowerCase();

		// cast all values to strings
		var day = ” + this.getDate(),
			month = ” + (this.getMonth() + 1),
			hour = ” + this.getHours(),
			minute = ” + this.getMinutes(),
			second = ” + this.getSeconds(),
			year = ” + this.getFullYear();

		// pad leading zeros
		if (showZeros) {
			if (1 === day.length) {day = ‘0′ + day;}
			if (1 === month.length) {month = ‘0′ + month;}
			if (1 === hour.length) {hour = ‘0′ + hour;}
			if (1 === minute.length) {minute = ‘0′ + minute;}
			if (1 === second.length) {second = ‘0′ + second;}
		}

		// use month name
		if (useMonthName) {
			month = (isType(useMonthName, ’string’) && ‘abbr’ === useMonthName.toLowerCase())? this.getMonthNameAbbr(): this.getMonthName();
		}

		return format.replace(’y', year)
					 .replace(’d', day)
					 .replace(’h', hour)
					 .replace(’i', minute)
					 .replace(’s’, second)
					 .replace(’m', month); // do month last as some months contain reserved letters
	},

	/**
	 * Converts JavaScript Date into a MySQL dateTime string ‘1969-12-31 00:00:00″
	 *
	 * @method toTimeString
	 * @return {string} the JavaScript Date as a MySQL time string
	 * @public
	 */
	toTimeString: function() {
		return this.toDateString(’y-m-d h:i:s’, true);
	}
}, true);

These are the few methods that I find immensely helpful for almost any project. The first two return either the month name or the abbreviated month name of the date. I first used this for a content management system and often find a need for them. ‘toDateString’ is one of my favorite functions and it converts a Date object into most useful date strings. I was writing a lot of PHP at the time and modeled it after the ‘date’ Function in PHP (it needs some work as it was written ages ago). Ideally, I could find the PHP source code and model my JavaScript objects after it, but this method has still been very useful anytime I needed to insert a Date from JavaScript into the page. The last method ‘toTimeString’ allows you to pre-format your MySQL date times, before sending them to the back-end… most languages will do these conversions for you, but I have occasionally found it useful (remember to always validate any parameter on the back-end before using one in a database query).

If you are looking for more functionality, YUI has a huge collection of date math static function in Calendar that you could also attach to the “Date.prototype”.