A jQueryplugin
that sets a div to allow recording an event to an iCalendar implementation,
as well as various utility functions for events.
The current version is 1.1.1 and is available
under the MIT licence.
For more detail see the documentation reference page.
Or see a minimal page that you could
use as a basis for your own investigations.
The iCalendar specification (RFC 2445)
defines a standard for 'interoperable calendaring and scheduling services for the Internet'.
The iCalendar functionality can easily be added to a division
with appropriate default settings - although you do need to specify some
of the details about the event itself. The resulting links allow the user
to post details about an event to any number of iCalendar sites.
You can also remove the iCalendar widget if it is no longer required.
Two types of iCalendar sites exist - external and local.
External ones exist on the Web and are invoked via a URL.
Local ones reside on your desktop and are transferred via the
clipboard (default) or via a textfield or a downloadable event file.
iCalendar with everyone:
Join us for an Australia Day lunch on your local beach
from 11:30 to 12:30 on January 26, 2008.
AustDayLunch = {start: new Date(2008, 1-1, 26, 11, 30, 00),
end: new Date(2008, 1-1, 26, 12, 45, 00),
title: 'Australia Day lunch',
description: 'A traditional barbeque for our big day',
location: 'On your local beach'};
$('#defaultICal').icalendar(AustDayLunch);
$('#removeICal').click(function() {
var destroy = $(this).text() === 'Remove';
$(this).text(destroy ? 'Re-attach' : 'Remove');
$('#defaultICal').icalendar(destroy ? 'destroy' : AustDayLunch);
});
You can override the defaults globally as shown below:
$.icalendar.setDefaults({tipPrefix: 'Save to '});
Processed fields are marked with a class of hasICalendar
and are not re-processed if targetted a second time.
$('#changeICal').icalendar(
$.extend({sites: ['yahoo', 'icalendar']}, AustDayLunch));
$('#changeButton').click(function() {
var google = $('#changeICal').icalendar('change', 'sites')[0] === 'yahoo';
$('#changeICal').icalendar('change',
{sites: google ? ['google', 'outlook'] : ['yahoo', 'icalendar']});
});
Local iCalendar Usage
For sites that are not external, such as iCalendar and Outlook, the iCalendar event
is used locally. By default, the event definition is copied into the clipboard
so that the user can paste it elsewhere. The copy is perfomed via a Flash
download to make it common across the browsers. Confirmation is required by the
user prior to the copy since they may not realise that the clipboard will be used
and may want to retain content already stored there.
Or provide a downloadable file by specifying an echo Web site
that correctly identifies the file type
(MIME type 'text/calendar', file extension '.ics').
You can add new sites to the list as shown below.
Note: this example is not a real iCalendar site.
The parameters are the id, display name, icon URL or index, and site URL.
A special site URL of 'echo' indicates that the iCalendar definition should be
used locally. Otherwise, within the site URL use:
'{t}' to mark the insertion point for the event's title
'{s}' for the event start date/time insertion point
'{e}' for the event end date/time insertion point
'{p}' for the event period (duration) insertion point
'{d}' for the event description insertion point
'{l}' for the event location insertion point
'{u}' for the event URL insertion point
'{c}' for the event contact insertion point
'{r}' for the event recurrence details insertion point
The following list shows the current sites with their IDs:
To be filled
var html = '';
$.each($.icalendar.getSites(), function(id, site) {
if (id != 'another') {
html += '<li>' + id + ' - ' + site.display + '</li>';
}
});
$('#siteList').html(html);
Styling
You can format the links with a bit of CSS. The structure of the links is shown below,
where the outermost div is the container you specify in your page:
This plugin provides a function for parsing the contents of an iCalendar definition.
The result is a JavaScript object that you can easily navigate for further processing,
e.g. ical.vevent.description.
Further iCalendar examples are available in the
specification.
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.
Parse source:
Parsed model:
$('#parseButton').click(function() {
var ical = $.icalendar.parse($('#parseInput').val());
$('#parseOutput').val($.toJSON(ical, true));
});
Duration Calculations
iCalendar allows for the definition of
durations,
for events and alarms amongst others.
They are defined as a number of weeks (PnnW),
or a number of days/hours/minutes/seconds (PnnDTnnHnnMnnS).
A duration may be prefixed by a negative sign (-) if it extends into the past.
This plugin provides two functions for dealing with these durations.
The first function calculates the duration between two date/times and
returns the value formatted for use within an iCalendar.
Calculate duration:
to
$('#calcDuration').click(function() {
var start = getDateTime('#date1', '#time1');
var end = getDateTime('#date2', '#time2');
$('#durationOut').val($.icalendar.calculateDuration(start, end));
});
The second function adds a duration to a start date/time to determine the end.
This tab highlights examples of this plugin in use "in the wild".
None as yet.
To add another example, please contact me (wood.keith{at}optusnet.com.au)
and provide the plugin name, the URL of your site, its title,
and a short description of its purpose and where/how the plugin is used.
Quick Reference
A full list of all possible settings is shown below.
Note that not all would apply in all cases. For more detail see the
documentation reference page.
$(selector).icalendar({
sites: [], // List of site IDs to use, empty for all
icons: 'icalendar.png', // Horizontal amalgamation of all site icons
iconSize: 16, // The size of the individual icons
target: '_blank', // The name of the target window for the iCalendar links
compact: false, // True if a compact presentation should be used, false for full
popup: false, // True to have it popup on demand, false to show always
popupText: 'Send to my calendar...', // Text for the popup trigger
tipPrefix: '', // Additional text to show in the tool tip for each icon
echoUrl: '', // The URL to echo back iCalendar content, or blank for clipboard
echoField: '', // The ID of a field to copy the iCalendar definition into,
// or blank for clipboard
start: null, // The start date/time of the event
end: null, // The end date/time of the event
title: '', // The title of the event
summary: '', // The summary of the event
description: '', // The description of the event
location: '', // The location of the event
url: '', // A URL with more information about the event
contact: '', // An e-mail address for further contact about the event
recurrence: null, // Details about a recurring event, an object with attributes:
// dates (Date or Date[]) or times (Date or Date[]) or
// periods (Date[2] or Date[][2] or [][Date, string]) or
// freq (string - secondly, minutely, hourly, daily, weekly, monthly, yearly),
// interval (number), until (Date), count (number), weekStart (number),
// by (object[] - type (string - second, minute, day, monthday, yearday,
// weekno, month, setpos), values (number or number[] or string or string[]))
// Confirmation message for clipboard copy
copyConfirm: 'The event will be copied to your clipboard. Continue?',
// Success message during clipboard copy
copySucceeded: 'The event has been copied to your clipboard',
// Failure message during clipboard copy
copyFailed: 'Failed to copy the event to the clipboard\n',
copyFlash: 'clipboard.swf', // The URL for the Flash clipboard copy module
// Clipboard not supported message
copyUnavailable: 'The clipboard is unavailable, please copy the event details from below:\n'
});
$.icalendar.setDefaults({...}); // Change global defaults
$.icalendar.addSite(id, display, icon, url, override); // Add a new iCalendar site
$.icalendar.getSites(); // Get the list of known iCalendar sites
$(selector).icalendar('change', settings); // Change settings for iCalendar instances
$(selector).icalendar('destroy'); // Remove iCalendar functionality
$.icalendar.formatDate(date); // Convert a date to the iCalendar format
$.icalendar.formatDateTime(dateTime, local); // Convert a date/time to the iCalendar format
$.icalendar.calculateDuration(start, end); // Get the duration between two date/times
$.icalendar.addDuration(start, duration); // Add a duration to a date/time
$.icalendar.parse(content, options); // Convert iCalendar text into a JavaScript object model
Usage
Include the jQuery library in the head section of your page.
Alternately, you can use the packed version
jquery.icalendar.pack.js (10.9K vs 29.6K), or the minified version
jquery.icalendar.min.js (12.3K, 4.8K when zipped).
Connect the iCalendar functionality to your divs or spans.