From the beginning, I’ve taken a very pragmatic approach with this plugin: I’ve built it and added new features primarily in response to user demand, trying to keep both the user experience and the code base as simple as possible. Of course over time it has grown quite complex, but I’ve still always tried to adhere to that pragmatic approach of only including features that I know people actually need.
iCalendar is a specification — a set of guidelines that programs are intended to adhere to for interoperability. It’s how you’re able to subscribe to a Google Calendar with your iPhone Calendar app, for instance, or how a collaborator using Microsoft Office 365 can send you a meeting invitation that gets added to your Google Calendar. If these programs weren’t using a common language to communicate, you wouldn’t be able to share data between them, and the specification (or “spec”) is the dictionary for that common language.
But like all languages, iCalendar has numerous dialects. Big tech companies want to do things their own way, both due to the inherent nuances of internal corporate culture but also because ultimately they are competing with each other and want to find an edge. So even though they all ostensibly support the iCalendar spec, they inevitably tend to deviate from the spec in one of three ways:
- Choosing not to support certain features
- Using certain features in ways other than how they’re defined in the spec
- “Extending” the spec with their own custom features
Anyone who was a web developer during the “browser wars” of the late 1990s and early 2000s, before the standards of HTML5 became widespread, will have firsthand, probably painful, knowledge of how this all goes down.
Which brings me to the details of the iCalendar spec, and which fields ICS Calendar needs to support. As an exercise in determining how well ICS Calendar is representing the most commonly used fields, I parsed the data from three sample Google Calendar feeds, three Microsoft Office 365 feeds, and one Airbnb feed. I found that across all seven of these feeds and a variety of types of event data, there were really only a small number of fields getting used on a regular basis. Let’s take a look at how these break down.
General feed data, control structures, and timezone information
BEGIN
CALSCALE
END
METHOD
PRODID
TZID
TZNAME
TZOFFSETFROM
TZOFFSETTO
VERSION
You’ll find BEGIN and END throughout an .ics file, serving a variety of purposes. They’re basically “opening” and “closing” tags in terms of the logical structure of the file, and will always be paired with something else: BEGIN:VCALENDAR for the overall document; BEGIN:DAYLIGHT for details of the beginning and end of Daylight Saving Time within the feed, BEGIN:VEVENT for each individual event, etc.
The fields beginning with TZ are timezone-related, and generally appear inside the BEGIN:DAYLIGHT structures.
The other fields listed here are relevant to the overall configuration of the calendar or information about the source server, but do not pertain to any individual events.
Event “meta data”
ACKNOWLEDGED
ACTION
CLASS
CREATED
DTSTAMP
LAST-MODIFIED
PRIORITY
RELATED-TO
STATUS
TRANSP
TRIGGER
UID
These fields do not contain displayable information about the event, but rather information about how or whether to display the event at all (specifically CLASS, STATUS and TRANSP), or more general information about when the event was created or modified. UID is a unique identifier for the event, and RELATED-TO uses UID values to link related events together.
ICS Calendar uses some of these fields, where relevant, especially CLASS for hiding private events, and UID for manipulating the data of a specific event, such as for generating the individual event download file when eventdl="true" is set in the shortcode. Other meta data fields, e.g. ACKNOWLEDGED or LAST-MODIFIED, do not really have any relevance for ICS Calendar.
Recurring events
Recurring events include some additional “meta data” fields:
EXDATE
RDATE
RECURRENCE-ID
RRULE
SEQUENCE
These fields are primarily used by the parser to calculate the actual dates and times of all of the recurrences.
Event information
Now we get to the heart of ICS Calendar’s displayed output for events. The following fields:
ATTACH
ATTENDEE
DESCRIPTION
DTEND
DTSTART
LOCATION
ORGANIZER
SUMMARY
URL
First, let’s scratch ATTENDEE. That is generally considered private information that would not be relevant to a public calendar, so we do not display it.
The DTSTART and DTEND fields store the date and time that each event begins and ends.
The SUMMARY field could be considered the “title” or “label” for the event, and it’s the text that displays next to the event’s start time in the calendar.
The DESCRIPTION field can contain a large block of text and even HTML. It is the text that gets displayed in the hover box or lightbox when a user hovers over or clicks on an event in the calendar to get more information. Popular systems like Google Calendar and Office 365 put almost all of the event’s information into this field, even if there are dedicated fields where it would be more appropriate.
The remaining fields, ATTACH, LOCATION, ORGANIZER and URL are also commonly used, when relevant, and ICS Calendar supports optionally displaying or hiding them.
…and the rest
Remember how I said individual vendors like to extend the spec to suit their purposes? In iCalendar, these are the X- fields, vendor-specific fields that serve a purpose within their systems, but most likely are totally ignored by any other software, including ICS Calendar.
Across the seven feeds I tested, here’s the full list of vendor-specific fields that appeared. Brace yourself.
X-ALARM-TRIGGER
X-ALT-DESC
X-APPLE-DEFAULT-ALARM
X-APPLE-NEEDS-REPLY
X-APPLE-STRUCTURED-LOCATION
X-APPLE-SUGGESTION-INFO-CHANGED-FIELDS
X-APPLE-SUGGESTION-INFO-CHANGES-ACKNOWLEDGED
X-APPLE-SUGGESTION-INFO-OPAQUE-KEY
X-APPLE-SUGGESTION-INFO-UNIQUE-KEY
X-APPLE-TRAVEL-ADVISORY-BEHAVIOR
X-BUSYMAC-LASTMODBY
X-ENTOURAGE_UUID
X-ENTOURAGEUUID
X-GOOGLE-CONFERENCE
X-GOOGLE-HANGOUT
X-KERIO-ORIGINAL-PRODID
X-LABEL
X-LIC-LOCATION
X-MICROSOFT-CDO-ALLDAYEVENT
X-MICROSOFT-CDO-APPT-SEQUENCE
X-MICROSOFT-CDO-BUSYSTATUS
X-MICROSOFT-CDO-IMPORTANCE
X-MICROSOFT-CDO-INSTTYPE
X-MICROSOFT-CDO-INTENDEDSTATUS
X-MICROSOFT-CDO-OWNERAPPTID
X-MICROSOFT-DISALLOW-COUNTER
X-MICROSOFT-DONOTFORWARDMEETING
X-MICROSOFT-EVENTPROPERTIESTODELETE
X-MICROSOFT-LATITUDE
X-MICROSOFT-LOCATIONCITY
X-MICROSOFT-LOCATIONCOUNTRY
X-MICROSOFT-LOCATIONDISPLAYNAME
X-MICROSOFT-LOCATIONPOSTALCODE
X-MICROSOFT-LOCATIONS
X-MICROSOFT-LOCATIONSOURCE
X-MICROSOFT-LOCATIONSTATE
X-MICROSOFT-LOCATIONSTREET
X-MICROSOFT-LOCATIONURI
X-MICROSOFT-LONGITUDE
X-MICROSOFT-ONLINEMEETINGCONFERENCEID
X-MICROSOFT-ONLINEMEETINGCONFLINK
X-MICROSOFT-ONLINEMEETINGINFORMATION
X-MICROSOFT-ONLINEMEETINGTOLLNUMBER
X-MICROSOFT-SCHEDULINGSERVICEUPDATEURL
X-MICROSOFT-SKYPETEAMSMEETINGURL
X-MICROSOFT-SKYPETEAMSPROPERTIES
X-MS-OLK-APPTSEQTIME
X-MS-OLK-AUTOSTARTCHECK
X-MS-OLK-CONFTYPE
X-NEXT-ALARM
X-WR-ALARMUID
X-WR-CALDESC
X-WR-CALNAME
X-WR-TIMEZONE
What about other fields in the iCalendar spec that aren’t listed here?
The weird thing about specifications is that they’re somewhat idealistic documents. The hope is that the vendors building software around these specs will honor them to the letter, but the reality is, that doesn’t happen. So we’re left with a number of well-considered fields that are nonetheless completely (or at least typically) ignored by the major vendors. I turned up these fields defined in the spec but not appearing in any of the sample feeds I reviewed:
CATEGORIES
COMMENT
COMPLETED
CONTACT
DUE
DURATION
FREEBUSY
GEO
PERCENT-COMPLETE
REPEAT
REQUEST-STATUS
RESOURCES
TZURL
Of these, CATEGORIES is definitely the most requested. Google Calendar and Office 365 let you color-code or otherwise “categorize” events, but that data is not passed through in the .ics file at all, and the CATEGORIES field would be a perfect place for it. I am aware that some less commonly used calendar programs do use this field though, so ICS Calendar has rudimentary support for it, in the form of HTML data attributes. There is no automatic visual styling of events based on CATEGORIES, but with access to these data attributes, site developers can add their own CSS or JavaScript to take advantage of it. Here’s how.
Several of the rest of these are probably not relevant to most uses of ICS Calendar, such as COMMENT, COMPLETED, DUE, PERCENT-COMPLETE or REQUEST-STATUS, all of which seem to pertain primarily to to-do lists. Likewise REPEAT is specific to alarms, so it is not relevant to ICS Calendar.
While FREEBUSY may seem to be relevant, it does not appear to be commonly used in feeds, so ICS Calendar does not (currently) support it. Likewise, TZURL does not appear to be used at this time — though my best interpretation of the spec is that it is designed to allow timezone/DST-related information to be updated in the future from an external URL… which may turn out to be useful if the United States passes laws currently under consideration to make Daylight Saving Time permanent year-round, for instance.
This leaves the following fields which ICS Calendar does not currently support, but may be worth consideration, and which we’ll look at individually:
CONTACT: This field is intended to contain contact information for the event. This certainly sounds like a useful field! But in practice I have yet to find a feed that is actually using it; instead, this data seems to generally be included in the ORGANIZER field. I am considering enhancing the existing organizer="true" parameter to include CONTACT as well, if it’s present in the feed.
GEO: This field is intended to include latitude and longitude coordinates for the event. Sounds great, but again I have not seen any feeds that actually include this. At present, ICS Calendar supports an option to auto-generate a Google Maps link based on the address held in the LOCATION field. It would not be a stretch to add support for GEO using the coordinates, although since I have yet to see a feed that includes this field, it will be difficult to test. (Related: I am also looking into adding an option to use OpenStreetMap as an alternative to Google Maps. That would apply to either LOCATION or GEO, once implemented.)
An interesting side note about GEO: Look at that vendor-specific list above. It includes X-MICROSOFT-LATITUDE and X-MICROSOFT-LONGITUDE, which should be put into the GEO field. Why doesn’t Microsoft use that field? I have only cynical answers to that question. (Even more interesting: Those fields did not appear in the Office 365 feeds I tested, but rather in a Google Calendar feed… on an event that was created from an invitation by an Office 365 user.)
RESOURCE: This is a field for information about resources needed for an event, such as intra-office room and equipment reservations. It makes perfect sense to include this as an option in ICS Calendar, but once again, I have not seen any feeds that actually contained this data, yet.
Conclusion
It does appear that there are three currently unsupported fields that are worthy of consideration for addition to ICS Calendar: CONTACT, GEO and RESOURCEs. The biggest challenge with adding any of these new types of features is that I really like to have real-world examples of feeds to work with for testing any functional changes, so I can be sure that the actual data ICS Calendar’s users have in their calendars is getting handled properly.
These options are now available as of version 10.9.0. CONTACT and GEO are integrated with the existing functionality of organizer="true" and location="maplinks" respectively. RESOURCES is a new option that you can display by adding resources="true" to your shortcode. You can also now choose Bing or OpenStreetMap as alternatives to Google when using location="maplinks", by adding mapsource="bing" or mapsource="openstreetmap" to your shortcode.
If your feed includes these fields, I’d like to hear from you! Please use the Pro Support Form to let me know.
—Scott