At the Forge - Sunbird and iCalendar

The way in which Sunbird structures these events and tasks strongly mirrors the vCalendar files in which they are stored. Although you might expect a modern Internet standard to use XML, iCalendar's file format consists of name-value pairs separated by a colon (:). Each event or task has its own begin or end line, and the entire calendar file similarly is nested between overall begin and end lines. Normally, each name-value pair in an iCalendar file sits on a single line. However, indenting a line with any whitespace means that it continues the data from the previous line, as in:

name:value
name2:
 value2
name3
 :value3

The above example defines three name-value pairs, each making slightly different use of whitespace. Sunbird normally uses the third option, such that each name is on a line by itself with its associated value indented on a subsequent line. Sunbird, as with other Mozilla products, puts all of its data files in a profile directory whose name is created randomly when you first start the program. The iCalendar files themselves are placed in the Calendar subdirectory within the profile directory.

The beauty of iCalendar is you aren't expected to have all of the calendar data in one file or even on one computer. An iCalendar-compliant program displays the union of all calendar data from all of the data files it has been instructed to read. You thus can have several different calendar files on your own computer, each of which reflects a different aspect of your life, for example, personal vs. professional. You also can retrieve calendar data files from other sources, including over HTTP, meaning that group calendars can be stored on a public server but displayed on your own computer.

When you first start Sunbird or when you first create a calendar with it, the program creates a CalendarDataFile.ics file. If you have more than one calendar, you end up with a number of such files on your system. Each file has the name CalendarDataFileN.ics, where N represents the number of the calendar you have created.

The structure of the file itself is pretty simple. For example, here is an iCalendar file with a single event, namely this month's Linux Journal deadline:

BEGIN:VCALENDAR
VERSION
 :2.0
PRODID
 :-//Mozilla.org/NONSGML Mozilla Calendar V1.0//EN
BEGIN:VEVENT
UID
 :05e55cc2-1dd2-11b2-8818-f578cbb4b77d
SUMMARY
 :LJ deadline
STATUS
 :TENTATIVE
CLASS
 :PRIVATE
X-MOZILLA-ALARM-DEFAULT-LENGTH
 :0
DTSTART
 :20050211T140000
DTEND
 :20050211T150000
DTSTAMP
 :20050209T132231Z
END:VEVENT
END:VCALENDAR

As you can see, the file begins and ends with VCALENDAR declarations. Each event is surrounded by BEGIN:VEVENT and END:VEVENT. Each event then has a unique ID; a summary, which normally is displayed in the calendar; a status; a class, which indicates whether you want to share this calendar information with others; and then the starting and ending times. It also has a timestamp showing when the event was last modified.

Timestamps in iCalendar files adhere to a slightly strange format of YYYYMMDD representing the date and then a T followed by the 24-hour clock time, followed by an optional time zone and a Z. Because I currently am living in Chicago, the timestamp represents not the time at which I made the entry, but the time it is in the time zone six hours ahead of me, one hour later than GMT (1Z).

What happens if I have a monthly deadline, and I want to include that in this calendar event? In Sunbird, I can go into the recurrence tab in the event editor by double-clicking on the event. There, I indicate that I want this event to repeat once every month, which changes the interface such that I'm now asked if it should be on the 11th of every month—that is, on the same date—or on the second Friday of every month, relative to the month. If I choose the first, my iCalendar file looks like this:

BEGIN:VCALENDAR
VERSION
 :2.0
PRODID
 :-//Mozilla.org/NONSGML Mozilla Calendar V1.0//EN
BEGIN:VEVENT
UID
 :05e55cc2-1dd2-11b2-8818-f578cbb4b77d
SUMMARY
 :LJ deadline
STATUS
 :TENTATIVE
CLASS
 :PRIVATE
X-MOZILLA-ALARM-DEFAULT-LENGTH
 :0
X-MOZILLA-RECUR-DEFAULT-UNITS
 :months
RRULE
 :FREQ=MONTHLY;INTERVAL=1
DTSTART
 :20050211T140000
DTEND
 :20050211T150000
DTSTAMP
 :20050211T132231Z
LAST-MODIFIED
 :20050211T153505Z
END:VEVENT
END:VCALENDAR

Notice how a RRULE property has been added, with values of FREQ=MONTHLY and INTERVAL=1. You might imagine that if I were to change this deadline to be every two weeks, it would be FREQ=WEEKLY and INTERVAL=2. This is true, except that it also adds a BYDAY=FR field, indicating that the event happens on Fridays.

If I choose to make this event occur on the second Friday of each month, the iCalendar file looks like this:

BEGIN:VCALENDAR
VERSION
 :2.0
PRODID
 :-//Mozilla.org/NONSGML Mozilla Calendar V1.0//EN
BEGIN:VEVENT
UID
 :05e55cc2-1dd2-11b2-8818-f578cbb4b77d
SUMMARY
 :LJ deadline
STATUS
 :TENTATIVE
CLASS
 :PRIVATE
X-MOZILLA-ALARM-DEFAULT-LENGTH
 :0
X-MOZILLA-RECUR-DEFAULT-UNITS
 :months
RRULE
 :FREQ=MONTHLY;INTERVAL=1;BYDAY=2FR
DTSTART
 :20050211T140000
DTEND
 :20050211T150000
DTSTAMP
 :20050211T132231Z
LAST-MODIFIED
 :20050211T153824Z
END:VEVENT
END:VCALENDAR

Notice how our RRULE property now is FREQ=MONTHLY, because this happens every month, with an INTERVAL=1. Also notice that BYDAY=2FR has been added, meaning that the event takes place on the second Friday of each month.

Finally, let's take advantage of Sunbird's ability to have remote calendars by moving this file out of our directory and onto another system. I move the CalendarDataFile7.ics file, which was so named because it was the seventh calendar I created, to /tmp. I then copy it to my Web site so it can be available at the URL http://reuven.lerner.co.il/CalendarDataFile7.ics. I double-check that the file is available from this URL by trying to download it using wget. When I see that it works fine, I know I can put this information into Sunbird.

Now I go into Sunbird and delete the ATF calendar; Sunbird won't let you remove the filename of an existing local calendar. I then choose subscribe to remote calendar from the File menu, and enter the URL at which I have placed my .ics file. Once the calendar has been downloaded, I see the LJ deadline event on my calendar each month, exactly as if it were on my local machine. And in fact, if you look in the Calendar directory, you can see that the file is on your local machine. It has been downloaded and installed into that directory, and it can be refreshed whenever you request. Simply right-click on the calendar name and select reload remote calendar).