vCalendar/iCalendar Addendum

This is an addendum to an article I wrote for phpbuilder.com on the vCalendar/iCalendar specification and PHP. There's no order to this article. Instead, I just want to touch upon a few things in more detail. Another caveat: this is no where near what the vCalendar and iCalendar specifications can do, and thus, not a subsitute for reading the specs yourself.

• Client Support Matrix
• vCalendar Recurrence Features Summary
• vCalendar Visual and Audio Alarms
• All Day Events

Client Support Matrix

As of this writing, 9/30/02, these are the major clients that support vCal/iCal, or both.

vCalendar Recurrence Features Summary

This is a summary from the vCalendar specs. I believe I've stuck with the official specification as close as possible. However, recurrence from vCal is a tricky business. I've yet to meet a client that can handle it perfectly. In fact, in some clients, it can't correctly handle its own vCal file. If you have an event that you export to vCal, then delete it from the program, then import the same program generated vCal file, the event won't correctly show up as recurring. If you're going to use recurrence, be aware that it may take a lot of work and testing to get it to work through the majority or clients.

There are four ways events can recur. They can recur:

• Daily
• Weekly
• Monthly
• Yearly

To make an event recur, add an element called RRULE to the VEVENT object:

RRULE:W2 WE FR #0

The RRULE value is made up of a frequency (W), interval(2), frequency modifier (WE FR), and an end date or duration (#0). The frequncey modifier is optional. It may not be applicable for some recurrence frequencies, and the syntax is different for each frequency.

Syntax

Frequency

The first character is a single letter that indicates how the event should recur. D means daily recurrence. W is weekly, M is monthly, and Y is yearly.

Interval

Intervals are an integer that tell how often a frequency should occur. 1 means every day, week, month, or year. 2 means every other day, week, month, or year. 3 means "every third." There is no limit to your interval value. Intervals work the same throughout all frequency rules.

Frequency Modifier

In the above example, the frequency modifier is "WE FR" Like I previously stated, the frequency modifier syntax changes for each frequency rule. The above example means "On Wednesdays and Thursdays." Obviously, this would be pretty useless when modifying yearly recurrence. I'll address frequency modifier when I get to the specific details of eachy frequency.

Duration

Duration is the final part of the RRULE value. Durations can be either the number of repetitions, (number of times the event should repeat) or repeat until (a specific date and time, in the vCal/iCal date time format). To specify the number of times, use the pound sign followed by an integer. #5 means repeat five times. #10 means repeat ten times. In our example, we use #0. #0 is a special duration indicator that means repeat forever.

In my limited testing, I have yet to find a client that can handle number of repetitions correctly, especially when it comes to #0. Instead, every client seems to handle repeat until correctly. Palm Desktop's calendar, for example, ends on December 31, 2031. That's fine because according to the Mayan Calendar and the series finalie of the X-Files, humans on earth ends on December 12, 2012. When you ask Palm Desktop to generate an event that repeats forever, it will give 20311231T000000 as the end date. Therefore, if you're targeting a wide variety of clients, use an end date far off into the future for the duration. For the following examples, however, I'm going to be lazy and use the #0 notation to denote "forever."

Durations work the same throughout all frequencey rules.

Frequency Rules

Daily

This rule is pretty straightforward. D is followed by the interval, and followed by the duration. There are no frequency modifiers for the daily rule.

Examples

Daily for the rest of 2002:
D1 20021231T000000

Every 10th day forever:
D10 #0

It may be pretty useless to use D7 (every seven days) because you'll get more flexibility from the weekly rule.

Weekly

Building on the very basic format of the Daily rule, we get the weekly rule. Instead of beginning with a D, we begin with a W. The weekly rule, however, uses two letter days of weeks as modifiers. Specifying a day of the week will make the event only occur on those days.

Examples

Every other Sunday forever:
W2 SU #0

Every Tuesday and Thursday until the end of October:
W1 TU TH 20021031T000000

Monthly

Now that we see how modifiers work, we can build upon the weekly rule to get the monthly rule. See how nicely this "build upon the last rule" thing works out? Monthly rules begin with M and followed by P or D. There are two types of modifiers available for the monthly rule: by-postion (MP) and by-day (MD).

By-Position Modifier

By-position means that the even repeats on a given day relative to its position in the month. For example, every third Monday of the month, or every first and second Friday in the month. By-position are made up of two parts: an offset integer and the same two character abbreviations of weekdays used in the weekly modifiers. The offset requires a plus or minus sign after the integer. The plus means ocurrence from the beginning of the month and the last means from the end of the month.

Examples

First and third Tuesday of every month:
MP1 1+ 3+ TU #0

Second to last Friday of every other month:
MP2 2- FR #0

By-Day Modifier

By-day modifier means that the event occurs on the nth day of every month. There is a special indicator, LD, which means last day. You can also use 1- for last day, 2- for second to last day, etc.

Examples

First of every fourth month:
MD4 1 #0

My paydays (15th and Last day of every month):
MD1 15 1- #0  (or MD1 15 LD #0)

Yearly

Like the monthly rule, there are two types of yearly rules. Yearly by-month (starts with YM) and yearly by-day (starts with YD).

By-month

By-month uses 1-12 as a numeric for each month following the yearly by month and interval indicators.

Examples

Every four years in February:
YM4 2 #10

Every year in June, July, and August:
YM1 6 7 8 #10

By-day

You can specify the number day from the beginning of the year (100th day, 200th day, etc.) with the YD indicator.

Every year on the 100th day:
YD1 100 #0

Every other year on the 243rd day:
YD2 243 #0

Alarms

There are two types of alarms: visual and audio. Visual alarms usually trigger a dialog box to be displayed by the client program. Audio alarms play a local file. Both types are optional in the specifications, and thus, should be used cautiously.

Alarms of both kind rely on the ISO 8601 time duration format for snoozes. The time duration format is a P, followed by an integer, followed by a Y, M, W, or D depending on if you want to specify years, months, weeks, or days, respecitively. Like the general iCal/vCal format, use a T to seperate the date portion from a time portion. Time portions are also an integer followed by a H, M, or S for hours, minutes, or seconds respectively.

Example

Twelve years:
P12Y

Two hours:
PT2H

3 years, 2 months, 20 days, 5 hours, 12 minutes, and 59 seconds:
P3Y2M20DT5H12M59S

Visual (Dispaly) Alarms

Visual, or Display, alarms are in the format:
DALARM:initial run time;duration of snoozes;number of times to repeat snoozes;Display string

Example

Reminder of Mom's birthday to be displayed one week before her birthday on August 28th, repeated daily.

DALARM:20020821T000000;P1D;7;Mom's birthday on the 28th.  Get a card! 

Audio Alarms

Audio alarms are best left to the client because the audio file should be a local file on the user's machine. However, if you really want to do it, format your audio alarm like this:
AALARM;TYPE=PCM, WAVE, or AIFF (depending on the sound file type);value=what the alarm is:initial run time;duration of snoozes;number of times to repeat snoozes;where the file is

Example

Audio alarm to dispaly 30 minutes before a meeting at noon on August 30th.  Plays a user's local sound file.  Snoozes every 10 minutes three times.

AALARM;TYPE=WAVE;VALUE=URL:20020830T113000;PT10M;3;file:c:\sounds\ping.wav