ical.js uses a layered approach towards parsing and processing iCalendar data.

iCalendar Data ↔ jCal Data ↔ Component Model Layer ↔ Item Model Layer

This is data in the iCalendar format, described by rfc5545. It can be converted to the jCal format, which is a JSON representation of the iCalendar data.

The following sections will reference properties of this example iCalendar data:

BEGIN:VCALENDAR
CALSCALE:GREGORIAN
PRODID:-//Example Inc.//Example Calendar//EN
VERSION:2.0
BEGIN:VEVENT
DTSTAMP:20080205T191224Z
DTSTART:20081006
SUMMARY:Planning meeting
UID:4088E990AD89CB3DBB484909
END:VEVENT
END:VCALENDAR

Here is an example on how to parse an iCalendar string to jCal:

var iCalendarData = "BEGIN:VCALENDAR" + /* ... */ + "END:VCALENDAR";
var jcalData = ICAL.parse(iCalendarData);

jcalData will now contain an array describing the VCALENDAR component, adhering to the jCal format. If iCalendarData contains more than one top-level component (i.e multiple VCALENDAR components concatenated) then ICAL.parse() will return an array of such components instead.

At this stage you have access to the raw jCal data. You can already use this representation to read simple information on the events in your data, but at some stage you will need one of the higher layers to process the data more easily.

Continuing the above example, the jCal object will look like this:

["vcalendar",
  [
    ["calscale", {}, "text", "GREGORIAN"],
    ["prodid", {}, "text", "-//Example Inc.//Example Calendar//EN"],
    ["version", {}, "text", "2.0"]
  ],
  [
    ["vevent",
      [
        ["dtstamp", {}, "date-time", "2008-02-05T19:12:24Z"],
        ["dtstart", {}, "date", "2008-10-06"],
        ["summary", {}, "text", "Planning meeting"],
        ["uid", {}, "text", "4088E990AD89CB3DBB484909"]
      ],
      []
    ]
  ]
]

This layer organizes the jCal data into components, subcomponents, properties, parameters, and values.

In the above example, vcalendar and vevent are considered components. summary is considered a property, the (currently empty) object inside the summary-array holds the parameters. The value is mapped to a rich object that contains methods to manipulate it, for example a date value.

This example retrieves the value of the summary property, using the jcalData from the above example:

var comp = new ICAL.Component(jcalData);
var vevent = comp.getFirstSubcomponent("vevent");
var summary = vevent.getFirstPropertyValue("summary");

In this layer, common properties on the known subcomponents can be easily retrieved. This layer is not yet complete. (If you would like to use more features here, please consider contributing to the ical.js code!)

This example achieves the same as in the previous example but using the Item Module Layer:

var comp = new ICAL.Component(jcalData);
var vevent = comp.getFirstSubcomponent("vevent");
var event = new ICAL.Event(vevent);
var summary = event.summary;

It may seem like more lines of code, but ICAL.Event has some other nice features that make it useful.

Please see the API docs for more complete documentation. If you come across a common use case you think should be included in these wiki docs, please do file an issue.