listEvents.do : Generating a Discrete List of Events

Bedework version 3.4.1.1

Action: listEvents

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

As of version 3.4.1.1 listEvents is only used to produce RSS and javascript feeds. It will be added to the tabs in version 3.5 alongside of Day-Month-Week-Year, though there needs to be some thought as to how to distinguish this listing from the "cal/list" toggle in the existing grid view. The existing "list" view takes the event data found on the calendar grid and presents it in list format divided up by days.

The request returns XML output which can be transformed into RSS, Javascript, HTML, etc. using Bedework's XSLT filter.

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

  • days=n (number of days to display)
  • start=yyyy-mm-dd (start date)
  • end=yyyy-mm-dd (end date - exclusive)
  • cat=catname (filter by a category)
  • cat=catname&cat=othercatname (filter by more than one category)

The parameters can be combined. The "days" parameter is always honored regardless of the "end" parameter until they overlap, in which case the "end" parameter always sets the outside limit. The "start" parameter always specifies the first day of the listing and defaults to "today" if not present.

An arbitrary number of category filters may be added to the query string.

Examples:

/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?days=7&start=2007-09-01&end=2007-09-05
returns five days worth of events (the "days" parameter is truncated by "end").

/listEvents.do?days=7&end=2007-12-31
Assuming today is Sept 1, 2007, this returns the next seven days’ events until we approach Dec 31, 2007, after which no events are returned. In the week preceding Dec. 31, this call will return 7 days, 6 days, 5 days, etc. until we pass the end date.

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

Output:

Events are represented as follows: 

:
:
<page>eventList</page>

<events>
  <event>
  :
  :
  </event>
</events>
:
:

Note: we would like to return the parameters for use in the UI, e.g. 

  <days>4</days>
  <start/>
  <end>20071231</end>

but we need to consider if these might be stored (rather than just passed through), combined with filters, etc. We will return them in some way in version 3.5.