jQuery iCalendar Reference

A jQuery plugin that sets a division to allow recording an event to an iCalendar implementation, as well as various utility functions for events. If you find this plugin useful please vote for it on the jQuery site.

This page provides a documentation reference for working with the plugin v1.1.1. See a demonstration of the iCalendar plugin and download the code from there. Or see a minimal page that you could use as a basis for your own investigations.

Instance Settings

A separate iCalendar instance is created for each targetted division with details of the event to be recorded:

$('div').icalendar({start: new Date(2008, 1-1, 26, 11, 30, 00),
	end: new Date(2008, 1-1, 26, 12, 45, 00),
	title: 'Australia Day lunch'});

Below are the options that may be applied to each iCalendar instance.

compact | contact | copyConfirm | copyFailed | copyFlash | copySucceeded | copyUnavailable | description | echoField | echoUrl | end | iconSize | icons | location | popup | popupText | recurrence | sites | start | summary | target | tipPrefix | title | url

NameTypeDefaultComments
sitesstring[][] List the IDs of the iCalendar sites to include. If none are specified, all are shown.
For example: $('div').icalendar({sites: ['google', 'icalendar'],...});
iconsURL'icalendar.png' The location of the icons for the standard iCalendar sites. This image is a horizontal amalgamation of all the individual icons.
iconSizeint16 The pixel size of the individual icons in the image above.
targetstring'_blank' The name of the window in which the external iCalendar links are opened. The default opens in a new tab/window. Set to '' to replace the current window.
compactbooleanfalse Set to true to display the links in a compact format using only the icons. When false, the icon and display name are shown.
popupbooleanfalse Set to true to have the list of calendar links appear on demand. When false, the calendar links are shown inline.
Since 1.1.0.
popupTextstring'Send to my calendar...' The text that appears as the trigger point for the popup list above.
Since 1.1.0.
tipPrefixstring'' Any text that should precede the site name in a popup tooltip for each site link.
echoUrlstring'' The URL that echoes back the iCalendar content (passed as the value of the content parameter) with the appropriate MIME type. If neither this nor echoField are specified, the iCalendar definition is copied to the clipboard for local targets.
echoFieldstring'' The ID of a field into which the iCalendar definition can be copied on selection. If neither this nor echoUrl are specified, the iCalendar definition is copied to the clipboard for local targets.
startDatenull The starting date/time for the event.
endDatenull The ending date/time for the event.
titlestring'' The title of the event.
summarystring'' A short description of the event.
descriptionstring'' A long description of the event.
locationstring'' The location of the event.
urlstring'' A URL for more information about the event.
contactstring'' An e-mail address to contact for more information about the event.
recurrenceobjectnull Details about recurrences of the event. See the recurrences object definition below.
Since 1.1.0.
copyConfirmstring'The event will be copied to your clipboard. Continue?' The message displayed to confirm that a copy to the clipboard should proceed. This is necessary as the user may not realise that the clipboard will be used and may wish to retain its current contents.
copySucceededstring'The event has been copied to your clipboard' The message displayed if a copy to the clipboard succeeds.
copyFailedstring'Failed to copy the event to the clipboard\n' The message displayed if a copy to the clipboard fails.
copyFlashstring'clipboard.swf' The URL for a Flash module that copies data to the clipboard. Set to '' to disable clipboard copy.
copyUnavailablestring 'The clipboard is unavailable, please copy the event details from below:\n' The message displayed if copying to the clipboard is unavailable, i.e. no copyFlash setting.

Recurrence Settings

An event may recur a number of times and the recurrence setting lets you specify those details. The settings below apply to a recurrence instance. All are optional. You should specify either one of dates, times, or periods, or a combination of the remaining settings.

recurrence: {dates: [new Date(2008, 2-1, 16), new Date(2008, 3-1, 6)]}
recurrence: {freq: 'monthly', count: 5, by: {type: 'day', values: '-2MO'}}

Since 1.1.0.

by | count | dates | freq | interval | periods | times | until | weekStart

NameTypeDefaultComments
datesDate or Date[]null Provide one or more dates on which the event recurs. Use this setting on its own.
timesDate or Date[]null Supply one or more date/times at which the event recurs. Use this setting on its own.
periods[Date, string or Date] or [][Date, string or Date]null Provide one or more time periods at which the event recurs. Each period is defined by either two date/times or a date/time and a duration. Use this setting on its own. 
periods: [new Date(2008, 2-1, 16, 8, 0, 0),
	new Date(2008, 2-1, 16, 9, 0, 0)]
periods: [[new Date(2008, 3-1, 6, 10, 0, 0), 'PT1H'],
	[new Date(2008, 4-1, 4, 12, 30, 0), 'PT30M']]
freqstringnull The frequency at which the event recurs. Valid values are 'secondly', 'minutely', 'hourly', 'daily' (default), 'weekly', 'monthly', 'yearly'.
intervalnumbernull The interval between recurrences. For example, a frequency of 'daily' and an interval of 3 indicates every third day. Omit for an interval of 1.
untilDatenull The date/time at which the recurrences end. Omit for no limit.
countnumbernull The number of times that the event recurs. Omit for no limit. If until is specified, this setting is ignored.
weekStartnumbernull The day that is the start of a week. Use 0 for Sunday, 1 for Monday (default), ..., 6 for Saturday.
byobject or object[]null Add one or more restrictions on the recurrences. Each entry in the array is an object with the following attributes:

type (string) one of 'second', 'minute', 'day', 'monthday', 'yearday', 'weekno', 'month', 'setpos'

values (number or number[] or string or string[]) the restricting values 
by: {type: 'monthday', values: [2, 15]}

Functions

addDuration | addSite | calculateDuration | change | destroy | formatDate | formatDateTime | getSites | parse | setDefaults

SignatureReturnsComments
$(selector).icalendar('change', settings)jQuery object Update the settings for the iCalendar instance attached to the given division(s).
$(selector).icalendar('destroy')jQuery object Remove the iCalendar functionality from the given division(s).
$.icalendar.setDefaults(settings)iCalendar object Update the default settings to use with all iCalendar instances.
$.icalendar.addSite(id, display, icon, url, override)iCalendar object Add a new iCalendar site definition.
id (string) is the identifier for this site and may be used in the sites setting to select this site
display (string) is the text to display for this site
icon (string) is the URL for an image to represent this site or (number) the icon's index within the icons setting
url (string) is the URL to which the iCalendar definition should be sent - within which you should use the following markers as substitution points for various event details: '{t}' for the event title, '{s}' for the event start date/time, '{e}' for the event end date/time, '{p}' for the event period (duration), '{d}' for the event description, '{l}' for the event location, '{u}' for the event URL, '{c}' for the event contact, or '{r}' for the event recurrence definition. A special site URL of 'echo' indicates that the iCalendar definition should be used locally - either downloaded or copied to the clipboard.
override (function, optional) is a function to allow for overriding the substitution values in the URL. The function receives an object containing the default insertions and the current settings object. The insertion object contains attributes named for the substitution points described above, e.g. inserts.t is the title, and should be updated with any changes.
Since 1.1.0 - override parameter and recurrence substition point.
$.icalendar.getSites()object Retrieve the collection of iCalendar site definitions. The entry is indexed by the site ID (string) and is an object containing the following attributes (as described in addSite): display, icon, url, and override.
$.icalendar.formatDate(date)string Convert a date into the iCalendar format (yyyymmdd).
date (Date) is the date to convert
Since 1.1.0 - previously handled both date and time.
$.icalendar.formatDateTime(date, local)string Convert a date/time into the iCalendar format (yyyymmddThhmmss[Z]).
dateTime (Date) is the date/time to convert
local (boolean, optional) is true if this is a local date/time (i.e. no timezone), or false if it is UTC
Since 1.1.0 - previously named formatDate.
$.icalendar.calculateDuration(start, end)string Determine the period between two date/times and present that as an iCalendar duration (PDnnTHnnMnnSnn). Returns '' if either parameter is missing.
start (Date) is the start of the period
end (Date) is the end of the period
$.icalendar.addDuration(start, duration)Date Apply an iCalendar duration (PDnnTHnnMnnSnn) to a starting date/time to determine the ending date/time. Returns the start date/time if the duration is missing. Throws an exception if the duration is invalid.
start (Date) is the start of the period
duration (string) is the duration specification
$.icalendar.parse(content)iCalendar object Parse an iCalendar text definition into a JavaScript object. The basic rules for conversion are:
  • All names are converted to lower case.
  • Names that are reserved words have an underscore (_) appended, e.g. CLASS becomes class_.
  • Simple entries (name and value only) are presented as attributes with string values.
  • Entries with additional parameters result in an object value with the _value field holding the original value.
  • Dates are converted into Date objects where possible and are annotated with a _type field to indicate their timezone: UTC, float (none specified), or a name.
  • Date ranges are converted into objects with start and end values.
  • Repeating fields are converted into arrays.
An exception is thrown if the definition is invalid.
content (string) is the iCalendar definition

For example:
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//hacksw/handcal//NONSGML v1.0//EN
BEGIN:VEVENT
DTSTART:19970714T170000Z
DTEND:19970715T035959Z
SUMMARY:Bastille Day Party
END:VEVENT
BEGIN:VEVENT
DTSTART:19980714T170000Z
DTEND:19980715T035959Z
SUMMARY:Bastille Day Party2
END:VEVENT
END:VCALENDAR
is converted to 
{
	version: "2.0",
	prodid: "-//hacksw/handcal//NONSGML v1.0//EN",
	vevent: [{
		dtstart: new Date(1997,07,14,17,00,00),
		dtend: new Date(1997,07,15,03,59,59),
		summary: "Bastille Day Party"
	},
	{
		dtstart: new Date(1998,07,14,17,00,00),
		dtend: new Date(1998,07,15,03,59,59),
		summary: "Bastille Day Party2"
	}]
}

Contact Keith Wood at kbwood{at}iinet.com.au with comments or suggestions.

Valid HTML 4.01 Strict