Permalink
Browse files

add license and documentation

  • Loading branch information...
1 parent 2813796 commit 0effb2a60eda4db0beb00ab0c1e05827effcf9f8 @tardate committed Oct 3, 2010
Showing with 88 additions and 24 deletions.
  1. +20 −0 MIT-LICENSE
  2. +40 −8 README.rdoc
  3. +4 −13 addtocal.htm
  4. +24 −3 jquery.addtocal.js
View
@@ -0,0 +1,20 @@
+Copyright (c) 2010 Paul GALLAGHER (http://tardate.com)
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
View
@@ -1,16 +1,48 @@
= jQuery.addtocal
+jquery.addtocal is a jQuery UI widget that provides "Add to Calendar" functionality for any website.
+
+Given event details, it allows users to add the event to any supported calendar system.
+
+Supported calendar systems:
+* Google Calendar
+* Microsoft Live Calendar
+* Yahoo! Calendar
+* 30boxes
+* Any iCal-compatible desktop application
+* Any vCalendar-compatible desktop application
+
+See the addtocal.htm demo file for an example of how to initialize and use jquery.addtocal.
+
+Using jquery.addtocal is simply a matter of initializing the widget, and attaching it to any DOM element that will
+hold a calendarable event in your application.
+
+You need to implement one method when initializing jquery.addtocal: getEventDetails( element ).
+It is called when a user selects a calendar to add an event to.
+The element parameter is the jQuery object for the event invoked.
+You must return an object packed with the relevant event details.
+How you determine the event attributes will depend on your page structure, and whether you are using a standard markup such as
+the {hCalendar microformat}[http://microformats.org/wiki/hcalendar].
+
+== Source
+For more information and source files, see the project's {github repository}[http://github.com/tardate/jquery.addtocalendar].
+Feel free to fork and enhance!
+
+== Dependencies
+
+* {jQuery 1.4.x}[http://jquery.com/]
+* {jQuery UI 1.8.x}[http://jqueryui.com/]
+* {rfc3339date.js}[http://github.com/tardate/rfc3339date.js]
== Copyright
-Copyright (c) 2010 Paul GALLAGHER
+Copyright (c) 2010 Paul GALLAGHER http://tardate.com
-Dual licensed under the MIT or GPL Version 2 licenses:
-* [http://www.opensource.org/licenses/mit-license.php]
-* [http://www.gnu.org/licenses/gpl.html]
+Dual licensed under the {MIT}[http://www.opensource.org/licenses/mit-license.php] or
+{GPL Version 2}[http://www.gnu.org/licenses/gpl.html] licenses.
== Other References
-* Google Calendar [http://www.google.com/googlecalendar/event_publisher_guide.html]
-* Windows Live Calendar [http://mailcall.spaces.live.com/blog/cns!CC9301187A51FE33!49778.entry]
-* Yahoo!, Google, iCal [http://davelms.co.uk/2006/09/04/add-to-calendar/]
-
+* {Google Calendar}[http://www.google.com/googlecalendar/event_publisher_guide.html]
+* {Windows Live Calendar}[http://mailcall.spaces.live.com/blog/cns!CC9301187A51FE33!49778.entry]
+* {Yahoo!, Google, iCal}[http://davelms.co.uk/2006/09/04/add-to-calendar/]
+* {hCalendar microformat}[http://microformats.org/wiki/hcalendar]
View
@@ -71,7 +71,8 @@
dtend_element = element.find('.dtend'), end,
title_element = element.find('.summary'), title,
details_element = element.find('.description'), details;
-
+
+ // in this demo, we attempt to get hCalendar attributes or otherwise just dummy the values
start = dtstart_element.length ? dtstart_element.attr('title') : new Date();
if(dtend_element.length) {
end = dtend_element.attr('title');
@@ -101,7 +102,8 @@
</head>
<body>
<h1>jquery.addtocal Demo</h1>
- <p class="description">This demonstrates the basic add-to-cal function.</p>
+ <p class="description">This demonstrates the basic add-to-calendar function.
+ For more information and source files, see the project's <a href="http://github.com/tardate/jquery.addtocalendar">github repository</a>.</p>
<div class="calendar-examples">
@@ -119,17 +121,6 @@
</div>
-<pre>
-/*
-* jQuery.addtocal
-*
-* Copyright (c) 2010 Paul GALLAGHER
-* Dual licensed under the MIT or GPL Version 2 licenses:
-* http://www.opensource.org/licenses/mit-license.php
-* http://www.gnu.org/licenses/gpl.html
-*
-*/
-</pre>
</body>
</html>
View
@@ -14,6 +14,11 @@
{
options: {
+ /*
+ * calendars is a collection of all the supported calendars and the method for formating
+ * the calendar link in each case. If you want to use a calendar system not supported here, you can
+ * extend or modify this array as required in widget setup.
+ */
calendars : [
{value: 1,
label:"Add to Google Calendar",
@@ -66,11 +71,19 @@
return ( eventDetails.vcalurl ? eventDetails.vcalurl : null );
} }
],
-
- selectedCalendarTarget: null,
+
+ /* icalEnabled: set if iCal links are to be supported (requires you to provide an iCal format resource) */
icalEnabled: true,
+ /* vcalEnabled: set if vCalendar links are to be supported (requires you to provide an vCalendar format resource) */
vcalEnabled: true,
+ /* getEventDetails is the most critical function to provide.
+ * It is called when a user selects a calendar to add an event to.
+ * The element parameter is the jQuery object for the event invoked.
+ * You must return an object packed with the relevant event details.
+ * How you determine the event attributes will depend on your page.
+ * The example below illustrates how to handle two formats of event markup.
+ */
getEventDetails: function( element ) {
return {
webcalurl: 'webcal://site.ics',
@@ -82,6 +95,10 @@
location: null, url: null};
},
+
+ /*
+ * sanitizeEventDetails cleans up and normalises the event details provided by getEventDetails
+ */
sanitizeEventDetails: function( eventDetails ) {
eventDetails.title = ( eventDetails.title ? encodeURIComponent( eventDetails.title ) : '' );
eventDetails.start = ( typeof eventDetails.start.toRFC3339UTCString == 'function' ?
@@ -94,13 +111,17 @@
return eventDetails;
},
+ /* records the currently selected calendar service */
+ selectedCalendarTarget: null,
+ /* positioning of the addtocal widget */
appendTo: "body",
position: {
my: "left top",
at: "left bottom",
collision: "none"
},
-
+
+ /* main method called on selection of calendar service */
select: function(event, ui) {
var eventDetails = ui.sanitizeEventDetails( ui.getEventDetails($(this)) );
var calendar_provider = $.grep(ui.calendars, function(element, index){

0 comments on commit 0effb2a

Please sign in to comment.