Options

containerId – default: #jMonthCalendar

Use this to configure where your calendar should be placed in the page. You must have a matching DOM element with the ID

$.jMonthCalendar.Initialize({ containerId: '#MyContainerId' }, null);

headerHeight – default: 50

This sets the height of the navigation header.

$.jMonthCalendar.Initialize({ headerHeight: 50 }, null);

firstDayOfWeek – default: 0

This determines which day of the week weeks should start on (default 0 refers to sunday). Monday is 1, Tuesday is 2, etc.

$.jMonthCalendar.Initialize({ firstDayOfWeek: 1 }, null);

calendarStartDate – default: new Date()

This determines which month to display when the calendar is first loaded. The default is to start in the current month (today).

$.jMonthCalendar.Initialize({ calendarStartDate: new Date(2009, 1, 1) }, null);

dragableEvents – default: true

This determines weather or not you want event blocks to be dragable. Note this depends on jquery.ui.dragable.

$.jMonthCalendar.Initialize({ dragableEvents: false }, null);

dragHoverClass – default: ‘DateBoxOver’

This is the css class that is added when an element is being hovered over an acceptable date cell.

$.jMonthCalendar.Initialize({ dragHoverClass: 'SomeCssClass' }, null);

navLinks (object of values)

These are the label text and switches to determine the header navigation.

$.jMonthCalendar.Initialize({ 	
	navLinks: {
		enableToday: true,
		enableNextYear: true,
		enablePrevYear: true,
		p:'‹ Prev', 
		n:'Next ›', 
		t:'Today',
		showMore: 'Show More'
	}
}, null);

Events

onMonthChanging

This event is triggered upon changing the calendar’s month. If the callback function returns false, the change will be prevented. Note: this would be an excelent point to do an AJAX call for the next months events.

// supply this callback as an option with the collowing signature
$.jMonthCalendar.Initialize({
    onMonthChanging(newDate) { ... }
}, null);
 
// AJAX call sample for more events
$.jMonthCalendar.Initialize({
    onMonthChanging(newDate) { 
 
    }
}, null);

onMonthChanged

This event is triggered after calendar’s month has been changed.

$.jMonthCalendar.Initialize({
    onMonthChanged(event, newDate) { ... }
}, null);

onEventLinkClick

This event is triggered when the anchor tag of the event is clicked. Note: good place to link out to another page.

$.jMonthCalendar.Initialize({
    onEventLinkClick(event) { 
        alert(event.data.Event);
    }
}, null);

onEventBlockClick

This event is triggered when the div container of the event is clicked. Note: this our the link click would be a good place to show tooltips.

$.jMonthCalendar.Initialize({
    onEventBlockClick(event) { 
        alert(event.data.Event);
    }
}, null);

onEventBlockOver

This event is triggered when your mouse is over the event div container.

$.jMonthCalendar.Initialize({
    onEventBlockOver(event) { 
        alert(event.data.Event);
    }
}, null);

onEventBlockOut

This event is triggered when you mouse moves off the event div container.

$.jMonthCalendar.Initialize({
    onEventBlockOut(event) { 
        alert(event.data.Event);
    }
}, null);

onDayLinkClick

This event is triggered when the user clicks on the label of the day (number in upper right corner)

$.jMonthCalendar.Initialize({
    onDayLinkClick(event) { 
        alert(event.data.Date);
    }
}, null);

onDayCellClick

This event is triggered when the user clicks on the cell that contains the event div containers.

$.jMonthCalendar.Initialize({
    onDayCellClick(event) { 
        alert(event.data.Event);
    }
}, null);

onDayCellDblClick

This event is triggered wehn the user double clicks ont eh cell that contains the event div containers.

$.jMonthCalendar.Initialize({
    onDayCellDblClick(event) { 
        alert(event.data.Event);
    }
}, null);

onEventDropped

This event is fired after a user drags and drops and event onto a new day.

$.jMonthCalendar.Initialize({
    onEventDropped(event, calEvent, newDate) { 
        alert(calEvent);
        alert(newDate);
    }
}, null);

onShowMoreClick

This event is triggered when the user wishes to “see more” events than what can be displayed in the cell. Note: this would be a good place to use a tooltip or dialog as well.

$.jMonthCalendar.Initialize({
    onShowMoreClick(dayEvents) { 
        // dayEvents is an array of events 
        alert(dayEvents.length);
    }
}, null);

Methods

Initialize(options, eventArray)

This is the main method needed to be called to get a calendar on the page. You can initialize it with the options and event callbacks mentioned above to get a more custom plugin.

$.jMonthCalendar.Initialize({ containerId: '#MyContainerId' }, []);

ChangeMonth(newDate)

This method will change the current selected month of the calendar. This method will fire the callback onMonthChanging and onMonthChanged.

$.jMonthCalendar.ChangeMonth(new Date(2009, 1, 1));

ReplaceEventCollection(eventArray)

This will replace all events in the plugin with the new event array passed in. This will clear all existing events being displayed and redraw all the events after the replacement.

$.jMonthCalendar.ReplaceEventCollection([]);

AddEvents(eventArray)

This method will add a single event to the plugin or an array of events by merging into the existing array of events. After which the method will clear all visible event on the calendar and draw the events in the updated array.

$.jMonthCalendar.AddEvents([]);

ClearEventsOnCalendar()

This method will remove all the events in the plugin and and remove any being displayed.

$.jMonthCalendar.ClearEventsOnCalendar();

Download location: jMonthCalendar-1.3.2-Beta

The biggest change in this release is how events are handled. Before I was not passing the DOM event back to you for control, I was simply just calling the methods you configured as options and passing parameters. Now, the original DOM event is bubbled up to the custom event in most cases. Along with the original DOM event I am also stuffing in the custom data for the callback into the jQuery event object.

jQuery provides a nice way of encapsulating the original DOM event into a jQuery event object. A property on that object is ‘data’ (which can be waht ever I want). So now, all custom events are mostly passed one single parameter (with the exception of onMonthChanging and onShowMoreClick); the jquery typed event. Inside that event object I have put the data I want to send back, like the date or event object clicked on. Don’t worry I will get to a sample of what I am talking about.

First I will start off by showing you the old way of doing it prior to this release.

OLD Way

$().ready(function() {
    var options = {
        onMonthChanging: function(dateIn) {
            // this could be an Ajax call to the backend to get this months events
            alert("on month changing");
            // $.jMonthCalendar.ReplaceEventCollection(events);
        },
        onEventLinkClick: function(calEvent) { 
            // calEvent will be the calendar event you clicked on
            alert("event link click");
            return true; 
        },
        onDayLinkClick: function(dateIn) { 
            // date might be wrong here, held reference from last item
            alert(dateIn.toLocaleDateString());
        }
    };
 
    $.jMonthCalendar.Initialize(options, []);
});

Okay, so the obvious problem with that is that there is no way to get to the original DOM event.

NEW recommended Way

$().ready(function() {
    var options = {
        onMonthChanging: function(dateIn) {
            // this could be an Ajax call to the backend to get this months events
            alert("on month changing");
            // $.jMonthCalendar.ReplaceEventCollection(events);
        },
        onEventLinkClick: function(event) { 
            // event is the jQuery event passed
            alert("event link click");
            // can get to the actual calendar event now through the Data property
            alert(event.data.Event);
            // want to prevent event bubbling use:
            event.stopPropagation();
        },
        onDayLinkClick: function(event) { 
            alert(event.data.Date.toLocaleDateString());
        }
    };
 
    $.jMonthCalendar.Initialize(options, []);
});

New Features:

• Dragable Events support using jQuery UI (Optional usage).
• Add ability to enable or disable calendar links (today link, next year, and previous year).
• Default Next and Previous link text changed.
• Added onDayCellDblClick event that passes the date you are double clicking.
• Added onEventDropped event that passes the event object and the new date being dropped into.
• Removed my custom Date extensions and replaced it with Datejs, more on this below.
• Complete Build Process to build, pack and minify the source.

The drag and drop stuff is pretty cool and makes the calendar even slicker. Have to provide props to the reader (Mattias Jakobsson) who took it upon their own to add it in. With the addition of the event when the event is dropped this would allow a developer to update an event using AJAX, allowing the user to easily reorganize events. jQuery UI is not a dependency and this feature is totally optional.

As for the date extension stuff, it was not something I wanted to maintain, and didn’t use that often. I hope to add another option in the setup to allow for a date parsing options on the inbound JSON.

Another item I am proud of is a unified build process. I wanted to make releases as easy as possible so I thought I would spend some time learning ANT and looking at other scripts (jQuery, Dojo, and other projects for JavaScript). I managed to write a pretty neat ANT script that will produce all the artifacts for a release and zip it up. I will save the details for another post.

The last point I will mention is now the ability to override the navigation links and turn them on or off depending on your usage. This was asked for and was a simple addition to source. If you have any suggestions, send them along I will add them in to the source if I feel they fit the project goal. Below is an updated definition of all the options available for the plugin.

FYI: The next release will make a change in how the calendar is sized and will absolutely position events over the calendar for Multi Day Event capabilities.

var defaults = {
	height: 650,
	width: 980,
	navHeight: 25,
	labelHeight: 25,
	firstDayOfWeek: 0,
	calendarStartDate:new Date(),
	dragableEvents: false,
	activeDroppableClass: false,
	hoverDroppableClass: false,
	navLinks: {
		enableToday: true,
		enableNextYear: true,
		enablePrevYear: true,
		p:'‹ Prev', 
		n:'Next ›', 
		t:'Today'
	},
	onMonthChanging: function(dateIn) { return true; },
	onMonthChanged: function(dateIn) { return true; },
	onEventLinkClick: function(event) { return true; },
	onEventBlockClick: function(event) { return true; },
	onEventBlockOver: function(event) { return true; },
	onEventBlockOut: function(event) { return true; },
	onDayLinkClick: function(date) { return true; },
	onDayCellClick: function(date) { return true; },
	onDayCellDblClick: function(dateIn) { return true; },
	onEventDropped: function(event, newDate) { return true; },
	locale: {
		days: ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"],
		daysShort: ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"],
		daysMin: ["Su", "Mo", "Tu", "We", "Th", "Fr", "Sa", "Su"],
		months: ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"],
		monthsShort: ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"],
		weekMin: 'wk'
	}
};

A few weeks ago I started down the path of setting up a new server/host using SliceHost for the purpose of installing a Subversion server and a RoR application Redmine. They are great, I can’t speak anymore highly of their product.  Everything got setup and installed perfectly as expected. I got the RoR app up quickly using Phusion Passenger which saved me a ton of pain.

Unfortunately I went to sleep worrying about how I was going to manage an application, open source project and still keep a secure Subversion repository and server while still being able to develop. The other night I decided I would save some and make by life simpler by moving the project over to code.google.com and ditch my slice.  Google Code will, now going forward, provide jMonthCalendar a project home, wiki, issues, downloads and Subversion source control. It currently allows anonymous Subversion browsing and the ability to add members to the project for collaborative development. Google code offers everything I would need for an open source project, allowing me to focus on the fun stuff, coding. Along with the new project home I also created a Google Group (found below) for open discussion, support, suggestions, etc. Please feel free to stop buy and check it out.

Comments and suggestions will be greatly appreciated, also if you are currently using jMonthCalendar please let me know, I would love to feature/link your site on the home page.  Happy Coding.

If you are interested in jMonthCalendar or looking for the new details, please see below.
Latest Release: jMonthCalendar 1.2.1 (bug fixes)
Downloads: http://code.google.com/p/jmonthcalendar/downloads/list
Project home: http://code.google.com/p/jmonthcalendar/
Google Group: http://groups.google.com/group/jmonthcalendar
Source Code: http://code.google.com/p/jmonthcalendar/source/list