vCalendar Crash Course
Here is a simple vCalendar file with one event:
BEGIN:VCALENDAR
VERSION:1.0
BEGIN:VEVENT
SUMMARY:New Volunteer Orientation
DESCRIPTION;ENCODING=QUOTED-PRINTABLE:Interested in becoming a volunteer for the Sacramento SPCA? We'd love to have you join our team! Please download a volunteer application from this website, and when you mail it in, indicate that you'd like to attend this orientation.=0D=0A=
=0D=0A=
Contact Dee Dee Drake for more information.
DTSTART:20020925T010000Z
DTEND:20020925T020000Z
END:VEVENT
END:VCALENDAR
Each vCalendar object begins with a
BEGIN:VCALENDAR statement and ends with a END:VCALENDAR statement. In-between are multiple events delimited by BEGIN:VEVENT and END:VEVENT. This is the general model for an element:
ELEMENTNAME;PARAMETER1=PARAMETER1VALUE:Element value.
Walking through our example, we set general calendar elements. They go before the first calendar event. There are several of these elements, but I won’t go into detail about them because only one, VERSION, is required. VERSION:1.0 indicates vCalendar and VERSION:2.0 indicates an iCalendar file. Check the official specifications on using and formatting the other general calendar elements. After the general elements, we see the first event delimited with the BEGIN:VEVENT statement.
Again, I won’t elaborate on every element available for an event. Instead, I will mention only the mandatory ones.
SUMMARY is a short description used widely in things like month/week/day calendar views.
DESCRIPTION is a detailed description of the event. Most software applications display the DESCRIPTION in a notes area or reveal it after the user clicks on the summary.
In our example, we see a use of an element parameter called
ENCODING with a value of QUOTED-PRINTABLE. If your description uses line breaks, you’ll need this parameter and value. Software applications probably can’t see HTML in its scheduling functions, so <br> means nothing. The vCalendar specification uses line breaks as element delimiters, so manual line breaks will not show up. To show line breaks in your description, you’ll have to encode the description with a value of QUOTED-PRINTABLE and use. =0D=0A= for line breaks, which is the hex value of a carriage return and new line.
DTSTART is the day and time the event starts. DTEND is the day and time the event ends. They both follow this format: YYYYMMDDTHHMMSSZ, where YYYY is the four digit year, MM is the two digit month, DD is the two digit day, T separates the date from the time, HH is the two digit hour, MM is the two digit minutes, and SS is the two digit seconds. The Z at the end is optional. If you have the Z, the time listed is in UTC, or Zulu time. The software application should automatically translate it to the user’s local time. Without the Z, the date and time is always local to the user. This is an important consideration if the users are in different time zones.
These elements are basically all you need to schedule an event. The official specification has many more elements that can be added. You can tickle a visual or audio alarm, set location properties for an event, or set up recurring events. However, like most industry specifications that depend on vendor support, there is little consistency in their support. Developer, beware.
