jQuery iCalendar Reference

Settings
Functions

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.

Name	Type	Default	Comments
sites	string[]	[]	List the IDs of the iCalendar sites to include. If none are specified, all are shown. For example: `$('div').icalendar({sites: ['google', 'icalendar'],...});`
icons	URL	'icalendar.png'	The location of the icons for the standard iCalendar sites. This image is a horizontal amalgamation of all the individual icons.
iconSize	int	16	The pixel size of the individual icons in the image above.
target	string	'_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.
compact	boolean	false	Set to true to display the links in a compact format using only the icons. When false, the icon and display name are shown.
popup	boolean	false	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.
popupText	string	'Send to my calendar...'	The text that appears as the trigger point for the popup list above. Since 1.1.0.
tipPrefix	string	''	Any text that should precede the site name in a popup tooltip for each site link.
echoUrl	string	''	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.
echoField	string	''	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.
start	Date	null	The starting date/time for the event.
end	Date	null	The ending date/time for the event.
title	string	''	The title of the event.
summary	string	''	A short description of the event.
description	string	''	A long description of the event.
location	string	''	The location of the event.
url	string	''	A URL for more information about the event.
contact	string	''	An e-mail address to contact for more information about the event.
recurrence	object	null	Details about recurrences of the event. See the recurrences object definition below. Since 1.1.0.
copyConfirm	string	'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.
copySucceeded	string	'The event has been copied to your clipboard'	The message displayed if a copy to the clipboard succeeds.
copyFailed	string	'Failed to copy the event to the clipboard\n'	The message displayed if a copy to the clipboard fails.
copyFlash	string	'clipboard.swf'	The URL for a Flash module that copies data to the clipboard. Set to '' to disable clipboard copy.
copyUnavailable	string	'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.

Name	Type	Default	Comments
dates	Date or Date[]	null	Provide one or more dates on which the event recurs. Use this setting on its own.
times	Date 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']]`
freq	string	null	The frequency at which the event recurs. Valid values are 'secondly', 'minutely', 'hourly', 'daily' (default), 'weekly', 'monthly', 'yearly'.
interval	number	null	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.
until	Date	null	The date/time at which the recurrences end. Omit for no limit.
count	number	null	The number of times that the event recurs. Omit for no limit. If `until` is specified, this setting is ignored.
weekStart	number	null	The day that is the start of a week. Use 0 for Sunday, 1 for Monday (default), ..., 6 for Saturday.
by	object 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

Signature	Returns	Comments
$(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" }] }`