Versions Compared

Old Version 3

changes.mady.by.user Barry Leibson

Saved on

compared with

New Version Current

changes.mady.by.user Arlen Johnson

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 5.3

...

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.  For more information, see the topics already covered in this chapter (section 4.5).

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. 

...

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.

...

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.)

...

• 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.

...

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”).

...

*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:

Code Block

:

:

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

  :

  :

  </event>
</events>

:

:

...

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.

...

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.

X-Property Name

Property Value

Parameters

Description

X-BEDEWORK-SUBMITTEDBY

Identity of event submitter

none

Assembles the userId of the event submitter, the group name, and the group userId

X-BEDEWORK-IMAGE

URL of image resource

X-BEDEWORK-PARAM-WIDTH
X-BEDEWORK-PARAM-HEIGHT
X-BEDEWORK-PARAM-DESCRIPTION

URL of image to be included with event description in web views

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):

Code Block

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

...

  • 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:

Code Block

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:

Code Block

<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