This week we added a calendar view of iteration (sprint) kickoffs and reviews, and of items with deadlines. Looks something like this:

To implement this, we used a fantastic jQuery plugin called FullCalendar written by Adam Shaw. This plugin is extremely well documented, easy to run, simple to configure and extendable. The minified Javascript file is 50kb and its CSS 10kb for a total of ~60kb download – not too big.

Basic Setup

Setting up the calendar was a breeze. Here’s the code to show the buttons in the header:

var calendar = $('#calendar');
calendar.fullCalendar({
	header: {
		left: 'title',
		center: 'today prev,next',
		right: 'month,basicWeek,basicDay'
	}, ...

As you can see, the header is split in 3 sections. Inside you specify what to see. How simple is that!

Styling the Calendar with CSS

FullCalendar can be styled using jQuery UI’s theme roller. Since we no longer use jQuery UI, I decided to modify the CSS myself. Fortunately, Adam has made a great use of class attributes on elements. For example, weekend cells have fc-sat and fc-sun classes. So here’s all I had to do to style those differently in my CSS:

#calendar .fc-sat,
#calendar .fc-sun {
	background-color:#F9F9F9;}

Adding Events to the Calendar

To fill the calendar, you populate it with events. At first, I got confused with the nomenclature thinking event was a Javascript event instead of a calendar event. Get over that hump and everything becomes crystal clear!

Adam gives you 3 choices to populate events:

1. Pass events as an array of event objects.
2. Pass events as a JSON URL. An AJAX call will fetch event objects.
3. Pass events as a function.

We used the last option in Planbox to call API function get_events, cycle through the returned Planbox events, create FulLCalendar events and then call the provided callback function with the built array.

...
events: function(start, end, callback) {
	args = {
		'product_ids': window.products.pluck('id'),
		'start': _.date2php(start),
		'end': _.date2php(end)
	};

	$.post('/api/get_events', args, function(data) {
		if (data.code == 'ok') {
			var events = [];
			var today = new Date();
			for (var i=0; i < object.content.length; i++) {
				var raw = object.content[i];
				events.push({
					title: raw.name,
					start: raw.due_on,
					data: raw
				});
			}
			callback(events);
		} else {
			alert(data.content);
		}
	});
}, ...

Custom Rendering

FullCalendar also provides callbacks for custom rendering. This is very useful if you want to modify the look of an event in the Calendar, or have a tooltip appear. We implemented the latter to show more information about the event. Here’s the code:

...
eventRender: function(event, element) {
	$(element).tooltip({
		content: template(event.data),
		addClass: 'event shadow'
	});
}, ...

Where story_template is an EJS template which renders the HTML in the tooltip.

Conclusion

Altogether I strongly recommend this calendar plugin. It is a pleasure to work with.

 

Martin

This entry was posted on Wednesday, September 7th, 2011 at 12:21 pm and is filed under Coding, Development. You can follow any responses to this entry through the RSS 2.0 feed. You can trackback from your own site.