The New Koha Calendar

by ByWater Staff on Oct 10, 2012

Anyone who has had interaction with the calendar in Koha within the last 2 major releases is probably missing chunks of hair about now. It’s buggy, rarely works with circulation or the dropbox, and doesn’t allow the integration of more granular time keeping. One of the large complaints with Koha currently is the inability to set the open/closed hours for your library in order to correctly circulate items. While there are patches currently being developed to address most of thebuggy-ness of the calendar none of them address the underlying issues. What I am aiming to do is a reset. A complete and total wipeout of all the existing calendar code anddata-structuresand start from scratch.

Design

I started by talking to some Koha community members about how they would like to see the calendar written. The general consensus was to have two object oriented modules: one for reads, one for writes. This would allow aseparationof logic as well as reduce overhead wheninstantiatingnew calendar objects. Next was to gather a list of all the places the calendar interacts with and all the functions it performs. After making the list I realized what a big project I had undertaken. The calendar interfaces with circulation when checking out, checking in and for special provisions. It also has its own page that allows users to input, update, and delete new unique or recurring events. Finally, the the thing it was lacking was the ability to add open/closed hours and use those just like it uses days.

The Database

I knew to tackle these problems I was going to need a solid design on the database side. The current calendar database structure looked like a mess. The years, months, and days were separate columns, there was a flag for exceptions (which I found out later was actually handy), repeating calendar weekdays were stored in a makeshift array that had to be parsed when being read, and there were two tables to handle the calendar that were non-normal. My approach to fixing the database was simple in thought harder in practice. I wanted to make one independent table for all events that will house the: id, name, description, branchcode, the event start datetime and the event end datetime. I then wanted to have a second dependent table for recurring events that would have the: id from its parent above, the recurrence start datetime (the first day of the first event), and the recurrence end time (the last day of the last event).

The UI

The current calendar in Koha had a list of events and asuper sizedjQueryui widget for the calendar. When there was an event it was color coded to match its type in the calendar. You clicked the calendar to get a form that allowed you to add a new event on that day. It was a simple solution to a problem that was simple a long time ago. Now that enhancements have been added it is really no longer a viable solution to keep up with current calendar operations. My redesign of the UI makes use ofAdam Shaw’s Full Calendar jQuery plugin. It also takes advantage of jQuery UI dialog boxes do allow users to add events in an overlay instead of moving elements around on a page with the sliding form. I will attach a beta video demo below.

The Logic

This was byfar the hardest part of getting the new calendar going in Koha. Single events are easy to deal with, but how does one handle recurring events. One of the main things I wanted to accomplish with this iteration of the calendar was infinitely recurring events. This complicates representing recurrences and displaying them because, as I’m sure you know, infinity isn’t represented well in discrete computing systems. My solution to solve the recurrence issue is to leverage the DateTime::Event::ICal module. This module allows me to pass a few parameters that define my recurrence and it will return a set of datetime span objects that are inclusive of my recurring dates.

The interesting part about dealing with these modules is it allows me to leverage set based operations on my data to manipulate it as I need. For example: I have two sets, one is myoriginalset of dates (Set A), the other is a set of sets (Set B) containing dates we are closed. I can then iterate over the set B taking the complement with respect to set A resulting in a set of dates on which we are open. Pretty cool huh?!

Demo

So while I finish integrating the new calendar into the rest of Koha I’d like to leave you with a demo of how the calendar will work. Check out the demo video here:http://www.screencast.com/users/libsysguy/folders/Jing/media/bbf715c0-6e31-47be-8b71-234567f8fa91 and let me know your thoughts in the comments section below.

[Originally posted by Elliott Davis]