Working with SiteBuilder Calendars
Download sitebuilder-calendars.js (19th March 2007)
This is a JavaScript file which contains some helper functions for fetching and manipulating data in SiteBuilder Calendars using the publicly available JSON output from the calendar.
Example usage:
<div id="upcomingcontent">
<img src="http://www2.warwick.ac.uk/static_war/images/tab-spinner.gif" border="0">
Loading...
</div>
<script type="text/javascript">
CalendarFetcher.printCalendar(
'/services/its/intranet/projects/webdev/sandbox/matmannion/calendar/',
'upcomingcontent','today',14,
'I have nothing in my diary for the next two weeks.');
</script> This will produce the following output:
Loading... Functions
| Function | Arguments | Description |
|---|---|---|
| CalendarFetcher.getCalendar | url, callback, [view], [days] | Fetches a JavaScript object representing the calendar for the relevant view (today, upcoming or latest). When the today view is chosen, the days argument specifies the number of days to get calendar items for. The url should be in the form /services/its/elab/about/people/matmannion/calendar/. When the operation completes, the calendar object is passed to the callback function specified. |
| CalendarFetcher.outputCalendar | calendar, element, [emptyMessage] | Given an element in the DOM and a JavaScript object representing the calendar, give a simplistic agenda output in the order of the items specified in the feed. The emptyMessage argument optionally specifies a message to show when there are no items in the calendar |
| CalendarFetcher.printCalendar | url, element, [view], [days], [emptyMessage] | Convenience function encompassing getCalendar and outputCalendar, outputting the contents of the calendar specified by the url into the element specified. |
Calendar Object Specification
For advanced users who wish to write their own callback functions for getCalendar to get a custom view (i.e., for those people for whom the outputCalendar callback is not satisfactory), here is the specification of the calendar object returned by getCalendar and passed into the callback.
Given a passed object calendar, the following fields are filled:
Calendar
| Function | Arguments | Description |
|---|---|---|
| calendar.id | String | A unique ID for the calendar - usually the URL to the calendar |
| calendar.title | String | The title of the page containing the calendar |
| calendar.description | String | A description of the data the object contains, e.g. Upcoming events, 20th February 2007 |
| calendar.links | Link[] | An array containing all Links to the calendar. In reality, will only ever contain one link (calendar.links[0]) - the link to the calendar itself |
| calendar.authors | Person[] | An array containing all Persons who own the calendar. In reality, will only ever return one person (calendar.authors[0]) - the Page Contact for the page containing the calendar |
| calendar.lastUpdated | Date | A JavaScript Date object specifying the date the calendar was last updated - usually the date the last event was added or modified |
| calendar.publicationDate | Date | A JavaScript Date object representing the date (in the server's eyes) that the JSON feed was generated |
| calendar.copyright | String | A copyright statement for the calendar, if any |
| calendar.categories | String[] | An array containing string representations of all tags used in the calendar |
| calendar.items | CalendarItem[] | An array containing all CalendarItems in the calendar. |
Link
| Function | Arguments | Description |
|---|---|---|
| link.href | String | The URL to the link |
| link.title | String | A title for this link. This may be null, and usually is for links in Calendars. |
| link.rel | String | The relation of the link to the calendar or calendaritem. One of: self, related, alternate, via, enclosure |
| link.length | long | The length of the target of the link in bytes. May be 0 if unknown |
Person
| Function | Arguments | Description |
|---|---|---|
| person.name | String | The name of the person |
| person.email | String | The email address of the person. This will never be filled in for SiteBuilder pages to avoid spam |
| person.url | String | The href to this person's homepage. May be null. |
CalendarItem
| Function | Arguments | Description |
|---|---|---|
| item.id | String | A unique ID for the item - usually the URL pointing to the item |
| item.title | String | The title of the event |
| item.url | Link | A Link to the URL for the item |
| item.summary | String | An abstract for the item, if one exists |
| item.content | String | Some text describing the item, showing when and where it is and either the detailed notes about the item or the abstract |
| item.publicationDate | Date | A JavaScript Date object specifying when the item was created |
| item.lastUpdated | Date | A JavaScript Date object specifying when the item was last updated (Note: This is usually set to the publicationDate even if it has been edited afterwards) |
| item.authors | Person[] | An array specifying the authors of the item as Person objects. As the item can only have one author, there is only one Person in this array - the Page Contact for the underlying Page. |
| item.categories | String[] | A String representations of all the tags for this calendar item. |
| item.start | Date | A JavaScript Date object for the start date for this event. |
| item.end | Date | A JavaScript Date object for the end date for this event. |
| item.location |
String | The location of the event, if given. |
Note: A different CalendarItem is created for every occurrence of an event if it is recurring. Also, the start and end times will always be given, even if they are not totally relevant. Where the item represents an all-day event, the start time is midnight for the day it is on and the end time is midnight on the following day. For an event, the start and end times are equivalent.
