Home

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

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

iCalendar Data

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 object adhering to the jCal format

jCal Data

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.

Based on the above example, the jCal object will look like this:

["icalendar",
  ["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"]
        ],
        []
      ]
    ]
  ]
]

Note: The outermost array is part of an older draft of the jCal specification, it will be removed in a later version. If you have trouble with this example, try assuming the ["vcalendar", ...] array is the top level object.

Component Model Layer

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 paramters. 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[1]);
var vevent = comp.getFirstSubcomponent("vevent");
var summary = vevent.getFirstPropertyValue("summary");

Note: As previously mentioned, the format of the jCal object will change. In this example the [1] will likely go away.

Item Model Layer

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 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[1]);
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.

Further Documentation

Currently, there is not much documentation (sorry!). You are going to have to look at the source files to figure out which methods are available. We are going to fix this using automated documentation generation in the future. In the meanwhile we hope the above examples will get you started.