Exposing Public Events

There are several ways users can access public events:

Calendar suites

Each calendar suite in your Bedework implementation can produce a custom web site with its own context, and you will need at least one calendar suite to display public events or to produce data feeds. 

Downloads

Events and whole calendars can be downloaded in iCalendar format from Bedework's web interfaces.   The downloads are suitable for any desktop calendar client such as MS Outlook and Apple's iCal.  They can be imported into other calendar systems as well. 

To download an event, look for the download icon on the event details page or in a list view.  To download a calendar, visit the “All Topical Areas” section of a public calendar suite and select the icon to download the calendar.  Calendars can be downloaded from today into the future, for past dates, or for a date range.

Subscriptions

Subscriptions to Bedework's public events can be pulled for use in Bedework's user client, where there is built in integration for subscribing to public calendars, and from any ical capable calendar client.  RSS and javascript feeds are also available (see “Data feeds” below).  The public CalDAV server allows access to any public Bedework calendar from CalDAV capable clients.

Data feeds - ical, raw xml, rss, json, js, etc.

Bedework 3.6 ships with a specialized application for serving data feeds: the “feeder” web app found at http://localhost:8080/feeder.  The feeder app comes with a number of skins, the default being clean XML. 

Bedework has a special action for generating a discreet list of events most useful to data feeds: the listEvents action.  If you want to produce feeds from other Bedework actions, see the stylesheet examples in the feeder app's “default” directory. 

Data feeds rely on XSL stylesheets to transform Bedework XML into a proper output format, except for the case of iCalendar feeds which are converted by the system directly.

Be aware: data feeds can potentially request large amounts of data which can be further compounded by a high request rate.  The core Bedework system should be protected by a front end caching system, and Bedework 3.6 ships with an example cache and URL builder packaged in Tomcat (see: http://localhost:9090/urlbuilder ).  For more information about the URL builder and web cache, see  the section 6.9 in this chapter,  “Cached Feed and URL Builder”. 

Several caching systems have been recently developed for use with Bedework.  Please visit the Bedework webite, wiki, and mailing lists for information about caching if you anticipate using the feed API directly against your system.

Action: listEvents

"listEvents.do" generates a listing of discrete events optionally filtered by categories or creator in a range of time. This listing is useful for RSS,  javascript, and ical feeds and for producing the traditional event list such as a printed Academic Calendar or agenda.

It is the view established in the "List" tab of the public and personal clients.

The request returns XML output which can be transformed into RSS, Javascript, HTML, etc. using Bedework's XSLT filter.   The quickstart comes with a number of XSL templates that handle conversion to various outputs.  For example, rss-list.xsl and json-list-src.xsl are default transforms for RSS and JSON feeds.  Look for these files in the application root for the public client (<quickstart>/bedework/deployment/webpublic/webapp/resources/).  Further instructions can be found at the top of the files.

The listEvents action can be used in two ways:

1.    Default: return a list of events from today through a specified number of days (e.g. RSS or agenda view); if no duration is supplied, return the next seven days.

2.    Return a list of events within a specified date range; if no start date is supplied, begin today. The maximum number of days returned is limited to 31. Requesting a range larger than this limit will return an error.

The action’s simplest form looks like:
http://localhost:8080/cal/listEvents.do
and returns the discrete events for the next seven days.

Parameters:

Time parameters:

• days=n (number of days to display forward from "today"; default is seven days.)

or

• start=yyyy-mm-dd (start date)

• end=yyyy-mm-dd (end date - exclusive. Optional - if unspecified, the default duration of seven days from the start date will be displayed.)

Calendar path:

• calPath=/public/cals/MainCal

• calPath=/public/cals/SomeOtherCal

• calPath=/public/cals/  (should return events from both MainCal and SomeOtherCal)

The calPath parameter constrains the query.  If you are building a link to a data feed,  best practice is to always send it.

Filters:

• catuid=categoryid (filter by a category)

• catuid=categoryid&catuid=othercategoryid (filter by more than one category)

• cat=catname (filter by a category name (less exact))

• cat=catname&cat=othercatname (filter by more than one category name)

• creator=creatorid (filter by creator, e.g. /principals/users/agrp_Somegroup)

Format:

•     format=text/calendar (forces the output into iCalendar format)

If no time parameter is included, the list will display "today" plus seven days. Time and filter parameters can be combined. An arbitrary number of category filters may be added to the query string.

A number of Bedework skins provide a means for arbitrary filtering, and are easily extended.  For example, the list-json.xsl skin found in the feeder app allows for the a key/value pair to be sent with a filter name as an application variable.  By extending this file you could, for example, send the parameter: “setappvar=filter(location:Jefferson Hall)” and then use this to filter events in the stylesheet.

Examples:

(note: these exclude the calPath parameter.  In most cases, you should append the calPath to the query string shown.  e.g.  “&calPath=/public/cals/MainCal”).

/listEvents.do?days=4
returns the next four days' events

/listEvents.do?start=2007-01-01
returns all events from Jan 1, 2007 forward (seven days)

/listEvents.do?start=2007-09-01&end=2007-10-01
returns discreet events from Sept 1, 2007 through Sept 31, 2007 (end date is exclusive)

/listEvents.do?catuid=ff808181-1fd7389e-011f-d7389eff-00000004
returns the next seven days worth of events filtered by the category "Exhibits" (as found in the quickstart). Note: this is the preferred method of selecting by exact category.

/listEvents.do?cat=Ballroom%20Dance
returns the next seven days worth of events filtered by the category "Ballroom Dance"

/listEvents.do?creator=/principals/users/agrp_SomeGroupId
returns the next seven days worth of events created by the group "agrp_SomeGroupId", where the group id is the "event owner" for the group.

/listEvents.do?days=3&catuid=ff808181-1fd7389e-011f-d7389eff-00000004
returns the next three days worth of events filtered by the category "Exhibits" (as found in the quickstart).

*http://localhost:8080/cal/main/listEvents.do?start=2009-06-07&format=text/calendar\* (http://localhost:8080/cal/main/listEvents.do?start=2009-06-07&format=text/calendar*)
returns events in icalendar format for seven days starting June 7, 2009

Output:

Events are represented as follows:

:

:

<page>eventList</page>
<events>
  <event>

  :

  :

  </event>
</events>

:

:

To output the data in RSS, append the query string with “&skinName=rss-list”, e.g.

/listEvents.do?days=4&skinName=rss-list

To output the data in json, append the query string with “&skinName=json-list-src”, e.g.

/listEvents.do?days=4&skinName=json-list-src

Starting with the rss-list.xsl or json-list-src.xsl files it is easy to build your own output types and data feeds.  For more information on these topics, see the chapter 6 “Bedework Theming” and the Bedework wiki: “Using json Feeds in Static Web Pages”.

http://www.bedework.org/trac/bedework/wiki/BedeworkManual/v3.6/DesignGuide/jsonFeeds

Cached Feed and URL/Widget Builder

The Cached Feed and URL Builder are packaged in the Tomcat server found in the Bedework quickstart and provide a way for users to produce cached data feeds and widgets for public events.

URL/Widget Builder

From the user's perspective it all starts here.  The user fills out a web form where she dictates which events she wants (lectures and seminars hosted by the School of Architecture, for example), over what timeframe (the next 21 days, the current month, etc.) and in what form (rss feed, iframe widget, etc.). For those looking for a feed, the form generates a URL that when clicked initiates a download (icalendar) or perhaps an invocation of their feed aggregators (rss). For those looking for a widget, the form writes some paste-able code into a text box.

CachedFeeder

CachedFeeder is written in Ruby and uses Ruby's page cache. Results that Bedework generates are mapped to a unique URL; each URL corresponds to a physical location in the cache's filestore. The filestore is hierarchical and follows the path components in the URL. As you'd expect, when a URL is requested, CachedFeeder first looks for the corresponding cache file. If the file exists, then it returns it. If it doesn't exist, the caching app calls Bedework's feeder application and caches the resulting file in the cache's file system store.

CachedFeeder uses jruby, an implementation of Ruby that generates JVM code, to compile the program into a war file for deployment.  The cache appears by default in <tomcat>/webapps/webcache/v1.0. Currently, cache pages aren't expired by the system. See http://www.bedework.org/trac/bedework/wiki/CachedFeeder/ExpiringEvents for some advice on expiring pages.

Feeder Application

The feeder application is a simplified version of the webclient application. It doesn't need nearly as much functionality, since the app only needs to worry about public event feeds.

Further documentation for the Cached Feed and URL Builder is maintained in the Bedework Wiki at http://www.bedework.org/trac/bedework/wiki/CachedFeeder

Adding custom properties (X-Properties) to events

X-Properties are a means of extending ical to define custom fields. They are useful for  site-specific data and for extending Bedework for site specific functionality, but be aware that while other calendar clients will preserve them, they will not display them.  For example, if a user downloads an event into outlook, your locally defined x-properties will not be seen.

All Bedework X-Properties take the following form:

X-BEDEWORK-PROPERTYNAME;param1;param2;param3:value

Bedework X-Property names are declared at the top of bedeworkXProperties.js. If you would like an X-Property to be considered for inclusion in Bedework, we suggest beginning the name with "X-BEDEWORK-".

Local properties can be named appropriately, e.g. X-MYUNIVERSITY-PROPNAME.

Bedework X-Properties

The following table lists two of the x-properties used by Bedework.  For more information about Bedework's x-properties, see the Bedework wiki.

Adding Custom X-Properties

Add custom X-Property handling to the setBedeworkXProperties() function of bedeworkEventForm.js. This function takes the event form object as a parameter; you can convert a custom form field to an x-property using the update() method of the x-property javascript object (declared in bedeworkXProperties.js in admin, submission, and user clients):

bwXProps.update(name,params,value,isUnique);

The update method takes the following parameters:

• name - name of the x-property, e.g. X-MYUNIVERSITY-GPSCOORDS
• params - series of key value pairs expressed in a 2-D array
• value - value of the x-property
• isUnique - true or false; if true, Bedework will only allow one x-property with this name.

Example:

function setBedeworkXProperties(formObj,submitter) {

  // set up specific Bedework X-Properties on event form submission
  // Depends on bedeworkXProperties.js
  // Set application local x-properties here.
  // X-BEDEWORK-IMAGE and its parameters:
  if (formObj["xBwImageHolder"] && formObj["xBwImageHolder"].value != ''){
    bwXProps.update(bwXPropertyImage,
                  [[bwXParamDescription,'An Orca!'],
                   [bwXParamWidth,'400'],
                   [bwXParamHeight,'300']],
                   formObj["xBwImageHolder"].value,true);
  }
  // X-BEDEWORK-SUBMITTEDBY
  bwXProps.update(bwXPropertySubmittedBy,[],submitter,true);

  // commit all xproperties back to the form
  bwXProps.generate(formObj);
}

Note: in this example, the image parameters are hard coded. The value of formObj["xBwImageHolder"] will be a url reference to an image.

X-Property Output

X-Properties are output within the event XML like so:

<event>

:

:

  <xproperties>
     <X-BEDEWORK-SUBMITTEDBY>
        <values>
           <text>caladmin for Communications (agrp_admGrp2)</text>
        </values>
     </X-BEDEWORK-SUBMITTEDBY>
     <X-BEDEWORK-IMAGE>
        <parameters>
          <X-BEDEWORK-PARAM-DESCRIPTION>An Orca!</X-BEDEWORK-PARAM-DESCRIPTION>
          <X-BEDEWORK-PARAM-WIDTH>400</X-BEDEWORK-PARAM-WIDTH>
          <X-BEDEWORK-PARAM-HEIGHT>300</X-BEDEWORK-PARAM-HEIGHT>
        </parameters>
        <values>
          <text>http://photography.naturestocklibrary.com/orca-stock-photo.jpg</text>
        </values>
     </X-BEDEWORK-IMAGE>
  </xproperties>


:

:

</event>

Note: if no parameters are present, they will not be output