##master-page:HelpTemplate
##master-date:Unknown-Date
#format wiki
#language en

== EventAggregatorSummary ==

The !EventAggregatorSummary action provides iCalendar and RSS summaries of events whose details are recorded in pages belonging to specific categories (such as CategoryEvents). These summaries can then be imported into applications which understand the iCalendar or RSS formats such as calendar and scheduling applications or feed readers.

Upon invoking the action, an iCalendar or RSS response will be produced. If the action is invoked in a browser, it is most likely that a dialogue box will appear asking you whether you would like to save the response to a file or to open the response in a suitable application. This behaviour is slightly different to many !MoinMoin actions.

== Using the Actions Menu Entry ==

The action can be selected from the actions menu on any page; this will produce a form requesting values for the following items:

 * The names of categories known to the Wiki.
 * The start (first month) of the summary (optional).
 * The end (last month) of the summary (optional).
 * The source of descriptions used in event summaries, taking either the event metadata or the comments made in the last edit of the event page.
 * The format of the summary: iCalendar or RSS 2.0.
 * The parent page can be specified in order to shorten any page names produced in a summary by removing their common parent (such as '''Events''' for pages called '''Events/Meeting''' and '''Events/Workshop''').

Where no start or end values are specified, all events in the chosen categories are included in the summary.

== Making Direct Requests to the Action ==

Alternatively, a collection of parameters can be specified in the URL of any Wiki page. For example:

{{{
http://example.com/moin/FrontPage?action=EventAggregatorSummary&category=CategoryEvents&doit=1
}}}

This should produce an iCalendar resource in response. By specifying `start` and `end` parameters, a restricted view can be obtained. For example:

{{{
http://example.com/moin/FrontPage?action=EventAggregatorSummary&category=CategoryEvents
&start=2009-06&end=2009-07&doit=1
}}}

This restricts the initial query to only retrieve events occurring in the months of June 2009 (`2009-06`) and July 2009 (`2009-07`).

=== RSS 2.0 Feeds ===

By adding the `format` parameter, an RSS feed resource can be produced:

{{{
http://example.com/moin/FrontPage?action=EventAggregatorSummary&category=CategoryEvents&doit=1&
format=RSS
}}}

This resource produces a description of all events within the stated criteria. Updated events should be detected by feed readers and each subscriber notified of such updates, with the comment made when the affected event was edited being provided as the event description in the feed.

A technical note: feed readers will typically detect updated events by consulting the content of each event description's `guid` element, notifying the user of changes if the content of that element has itself changed.

== Time Information in Summaries ==

The iCalendar format makes extensive use of time information and can employ complicated data structures in order to try and represent event times correctly. !EventAggregator has the following level of support for iCalendar features:

 * (./) Times applying everywhere or in an implicit time zone ("floating" times).
 * (./) Times specified in the UTC time zone.
 * {X} Times specified according to a particular time zone definition.

The last of the above features involves the replication of a time zone specification for a particular time "regime", and this is arguably error-prone as well as requiring the production of large amounts of largely irrelevant information in every downloaded summary.

!EventAggregator attempts to automatically convert time "regime" information (such as '''Europe/London''') to UTC for use in summaries. See the documentation on [[HelpOnEventAggregator#TimeProblems|problems with time information]] for some issues that might arise in some uncommon situations.

== See Also ==

 * HelpOnEventAggregator - a macro producing event calendars and listings