# HG changeset patch # User Paul Boddie # Date 1311460340 -7200 # Node ID 1b58d6c9f6cc58edb2426941b58b2f7d35d0f318 # Parent 29ae49e06183a0db838c8d98704277bc140a15db Added help on using event sources along with an example sources page. Removed the "to do" item about calendar navigation since such navigation is always provided if a calendar is named. diff -r 29ae49e06183 -r 1b58d6c9f6cc TO_DO.txt --- a/TO_DO.txt Sun Jul 24 00:02:18 2011 +0200 +++ b/TO_DO.txt Sun Jul 24 00:32:20 2011 +0200 @@ -13,9 +13,6 @@ Support caching of remote event data. -Support navigation where the full extent of external events cannot be -detected. - Localised Keywords ------------------ diff -r 29ae49e06183 -r 1b58d6c9f6cc pages/HelpOnEventAggregator --- a/pages/HelpOnEventAggregator Sun Jul 24 00:02:18 2011 +0200 +++ b/pages/HelpOnEventAggregator Sun Jul 24 00:32:20 2011 +0200 @@ -5,12 +5,14 @@ == EventAggregator == -The !EventAggregator macro for !MoinMoin can be used to display event calendars or listings which obtain their data from pages belonging to specific categories (such as CategoryEvents). +The !EventAggregator macro for !MoinMoin can be used to display event calendars or listings which obtain their data through "aggregation" from pages belonging to specific categories (such as CategoryEvents) or from remote event sources. -<> +<> == Creating Events == +(!) This documentation discusses only the creation of events on Wiki pages. It is also possible to collect or "aggregate" events from other sources, but the use of such sources is beyond the scope of this text. + The easiest way to create an event is to hover over a day number in a calendar and to follow the "New event" link, or if the calendar is being shown as a list, map or table, to select the "New event" link below the calendar content. If you do not have a calendar set up, take a look at the instructions for [[#PreparingACalendar|preparing]] and [[#ShowingEventCalendars|showing]] calendars first. Each event must be created on a new page belonging to the appropriate event category. The following action can be used to create a new event page (using [[HelpOnEventAggregatorNewEvent|EventAggregatorNewEvent]]) without looking at a calendar: @@ -138,11 +140,19 @@ <> == Preparing a Calendar == -Before trying to show a calendar or trying to create any events, first decide on a category for your events. You can create a new category for this purpose by filling out and submitting this form: +Before trying to show a calendar or trying to create any events, you must either decide on a category for your events or on an event source which will provide events to the Wiki. Or you can choose to show a calendar based on both categories and event sources. + +You can create a new category for the purpose of managing events by filling out and submitting this form: <> -It is not strictly necessary to have a dedicated category for events, but having such categories can make event management easier by preventing event pages getting mixed up with other kinds of pages. And since pages can belong to more than one category, you can still assign event pages to other categories and yet isolate the event pages via their own category when you need to. +Available event sources should be defined on the [[EventSourcesDict|event sources]] page, and the source name is the piece of information to be noted when preparing a calendar. + +Where categories are to be used, it is not strictly necessary to have a dedicated category for events, but having such categories can make event management easier by preventing event pages getting mixed up with other kinds of pages. And since pages can belong to more than one category, you can still assign event pages to other categories and yet isolate the event pages via their own category when you need to. + +=== Defining Event Sources === + +!EventAggregator uses a page called EventSourcesDict to define providers of event information (unless the `event_aggregator_sources_page` configuration setting has been changed). Follow the instructions on the EventSourcesDict page to define new event sources. <> == Showing Event Calendars == @@ -156,6 +166,20 @@ The calendar, shown by default, is automatically filled out with the details of each event in the specified category (or categories), colouring each event period in an automatically generated colour. +To use event sources instead of categories, specify them using `source` parameters. For example: + +{{{ +## Show events from the GriCal and FSFE sources. +<> +}}} + +Categories can be combined with sources, thus aggregating "internal" and "external" events: + +{{{ +## Show events from the Events category and the GriCal source. +<> +}}} + Specific periods can be defined using the `start` and `end` parameters. For example: {{{ diff -r 29ae49e06183 -r 1b58d6c9f6cc resource_pages/EventSourcesDict --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/resource_pages/EventSourcesDict Sun Jul 24 00:32:20 2011 +0200 @@ -0,0 +1,7 @@ +The following event sources are defined for !EventAggregator: + + GriCal:: http://grical.org/s/?query=%23free-software+{start}+{end}&view=ical ical + +To add a new source, extend the above definition list, putting the name of the source (to be used with the !EventAggregator macro) as the definition title, and putting the source's URL and the format of the data provided by the source, separated by whitespace, as the definition body. + +Currently, `ical` is the only supported format, referring to iCalendar (RFC 2445 and RFC 5545).