1 Introduction
2 ------------
3
4 The EventAggregator macro for MoinMoin can be used to display event calendars
5 or listings which obtain their data from pages belonging to specific
6 categories (such as CategoryEvents) or from remote event sources. The start
7 and end dates are read from the page describing each event, and the calendar
8 is automatically filled out with the details of each event, colouring each
9 event period in a specially generated colour. Maps showing event locations are
10 also supported, given the availability of appropriate map images and location
11 information.
12
13 The EventAggregatorSummary action can be used to provide iCalendar and RSS
14 summaries of event data based on pages belonging to specific categories, as
15 described above. The category, start and end parameters are read directly from
16 the request as URL or form parameters: these restrict the extent of each
17 generated summary.
18
19 The EventAggregatorNewEvent action can be used to conveniently create new
20 event pages, displaying a simple form which can be filled out in order to
21 provide elementary event details such as the event title or summary, the
22 categories to which the page will be assigned, and the start and end dates of
23 the event.
24
25 The eventfeed script can be used to import events from RSS feeds, inserting
26 new pages into a Wiki.
27
28 Important Notices
29 -----------------
30
31 In release 0.9, much of the common support code has been moved to the
32 MoinSupport distribution, thus introducing that distribution as a dependency
33 which must be installed for EventAggregator to work. See the documentation
34 regarding dependencies for further details.
35
36 Release 0.8.4 fixes time zone offset calculations for time regimes west of the
37 prime meridian.
38
39 Release 0.8.3 fixes end dates in events aggregated from remote iCalendar
40 sources.
41
42 Release 0.7.1 restores MoinMoin 1.9.x compatibility which was accidentally
43 lost in the 0.7 release.
44
45 Release 0.6.2 fixes various bugs in HTML production done by the actions. It is
46 strongly recommended to upgrade from earlier versions to this or a later
47 release.
48
49 In release 0.6.2, support for MoinMoin 1.5.x has been dropped. Since usage of
50 the Xapian search software is practically a necessary part of deploying this
51 solution, and yet Xapian only became integrated with MoinMoin from version 1.6
52 onwards, few deployments should have involved MoinMoin 1.5.x.
53
54 In release 0.6, support for event times has been introduced. Due to the
55 complicated nature of times, time zones, time regimes, and so on, the
56 behaviour of the software may change in future versions to support common
57 use-cases in a more convenient fashion. Please be aware that implicitly chosen
58 or generated time or time zone information may change for events, particularly
59 those whose times are ambiguous or ill-defined. It is highly recommended that
60 the pytz library be installed - see the documentation regarding dependencies
61 for more information.
62
63 In release 0.5, the "download this calendar" and "subscribe to this calendar"
64 links have been fixed to return only events within the specified period and to
65 work with day- and month-relative calendars. Users who have bookmarks in their
66 Web browser or feed reader should replace these bookmarks by visiting the
67 bookmarked page and acquiring new versions of these links, once
68 EventAggregator has been upgraded.
69
70 Installation
71 ------------
72
73 To install the support library and MoinMoin-related scripts, consider using
74 the moinsetup tool. See the "Recommended Software" section below for more
75 information.
76
77 With moinsetup and a suitable configuration file, the installation is done as
78 follows with $EADIR referring to the EventAggregator distribution directory
79 containing this README.txt file:
80
81 python moinsetup.py -f moinsetup.cfg -m install_extension_package $EADIR
82 python moinsetup.py -f moinsetup.cfg -m install_actions $EADIR/actions
83 python moinsetup.py -f moinsetup.cfg -m install_macros $EADIR/macros
84 python moinsetup.py -f moinsetup.cfg -m install_parsers $EADIR/parsers
85 python moinsetup.py -f moinsetup.cfg -m install_theme_resources $EADIR
86 python moinsetup.py -f moinsetup.cfg -m edit_theme_stylesheet screen.css event-aggregator.css
87 python moinsetup.py -f moinsetup.cfg -m edit_theme_stylesheet print.css event-aggregator.css
88 python moinsetup.py -f moinsetup.cfg -m edit_theme_stylesheet print.css event-aggregator-print.css
89
90 The first command above uses the setup.py script provided as follows:
91
92 python setup.py install --prefix=path-to-moin-prefix
93
94 The second, third and fourth commands install the actions, macros and parsers
95 respectively.
96
97 The fifth command installs the theme resources in the available theme
98 directories.
99
100 The remaining commands activate the styles provided by EventAggregator by
101 editing the screen.css and print.css files which are typically provided by
102 themes. These commands add imports of the following form to the theme
103 stylesheets:
104
105 @import "event-aggregator.css";
106
107 Optional Installation Tasks
108 ---------------------------
109
110 To add the capability of aggregating iCalendar format event sources, the
111 vContent software needs to be obtained and installed. See the "Recommended
112 Software" section below for details.
113
114 The following command can be run with $VCDIR referring to the vContent
115 distribution directory:
116
117 python moinsetup.py -f moinsetup.cfg -m install_extension_package $VCDIR
118
119 This merely runs the setup.py script provided by that software, installing
120 the software under the configured installation "prefix".
121
122 Useful Pages
123 ------------
124
125 The pages directory contains a selection of useful pages using a syntax
126 appropriate for use with MoinMoin 1.6 or later. These pages can be created
127 through the Wiki and their contents copied in from each of the files. An
128 easier installation method is to issue the following commands:
129
130 python moinsetup.py -f moinsetup.cfg -m make_page_package $EADIR/pages pages.zip
131 python moinsetup.py -f moinsetup.cfg -m install_page_package pages.zip
132
133 You may need to switch user in order to have sufficient privileges to copy the
134 page package into the Wiki. For example:
135
136 sudo -u www-data python moinsetup.py -f moinsetup.cfg -m install_page_package pages.zip
137
138 Resource Pages
139 --------------
140
141 For the map view, some resource pages are provided with EventAggregator.
142 Unlike the help pages which are most likely to be left unedited, the resource
143 pages should be modified and updated with additional map and place details.
144 Consequently, upgrading these pages is not necessarily desirable when new
145 releases of EventAggregator are made available, and thus these pages are kept
146 separate from the help pages.
147
148 To install the resource pages, use the following commands:
149
150 python moinsetup.py -f moinsetup.cfg -m make_page_package $EADIR/resource_pages resource_pages.zip
151 python moinsetup.py -f moinsetup.cfg -m install_page_package resource_pages.zip
152
153 You may need to switch user in order to have sufficient privileges to copy the
154 page package into the Wiki. For example:
155
156 sudo -u www-data python moinsetup.py -f moinsetup.cfg -m install_page_package resource_pages.zip
157
158 Using the Macro
159 ---------------
160
161 It should now be possible to edit pages and use the macro as follows:
162
163 <<EventAggregator(CategoryEvents)>>
164
165 As arguments to the macro, you must indicate a comma-separated list of
166 categories to be inspected for event data. For example:
167
168 <<EventAggregator(CategoryEvents,CategoryTraining)>>
169
170 By default, this should display a calendar in a collection of tables, one for
171 each month containing events. To show a collection of month-by-month listings,
172 use the 'mode' argument as follows:
173
174 <<EventAggregator(CategoryEvents,mode=list)>>
175
176 To use remote event sources instead of categories in the Wiki, specify each
177 source using explicit source parameters:
178
179 <<EventAggregator(source=GriCal,source=FSFE)>>
180
181 This will aggregate events from the GriCal and FSFE calendars residing on
182 remote Web sites, provided that these sources have been defined in the event
183 sources dictionary.
184
185 To use a search pattern, use the search parameter and specify the search
186 criteria just as you would when using the standard search macros:
187
188 <<EventAggregator(search="title:MonthCalendarEvents/")>>
189
190 This will aggregate events found on subpages of the MonthCalendarEvents page.
191
192 See pages/HelpOnEventAggregator for more detailed information.
193
194 Using the Actions
195 -----------------
196
197 To obtain an iCalendar summary, the EventAggregatorSummary action can be
198 selected from the actions menu on any page. Alternatively, a collection of
199 parameters can be specified in the URL of any Wiki page.
200
201 See pages/HelpOnEventAggregatorSummary for more detailed information.
202
203 To create new events using the EventAggregatorNewEvent action, the appropriate
204 menu entry can be selected in the actions menu. Alternatively, clicking on a
205 day number in a calendar view will invoke the action and pre-fill the form
206 with the start date set to the selected day from the calendar.
207
208 See pages/HelpOnEventAggregatorNewEvent for more detailed information.
209
210 Running the Scripts
211 -------------------
212
213 Note that remote event sources are likely to be more useful than the scripts
214 described below. However, these scripts may be useful for certain kinds of
215 application.
216
217 To import events from an RSS feed, the eventfeed script integrated with the
218 moin program can be used as follows:
219
220 moin --config-dir=path-to-wiki --wiki-url=example.com/ \
221 import eventfeed --url=url-of-events-feed
222
223 Thus, to import events from the FSFE events RSS feed, the following command
224 could be used:
225
226 moin --config-dir=path-to-wiki --wiki-url=example.com/ \
227 import eventfeed --url=http://www.fsfe.org/events/events.en.rss
228
229 If this command is being used with sudo, make sure to use the -u option so
230 that the script can operate as the appropriate user. For example:
231
232 sudo -u www-data moin --config-dir=path-to-wiki --wiki-url=example.com/ \
233 import eventfeed --url=http://www.fsfe.org/events/events.en.rss
234
235 It may also be necessary to set PYTHONPATH directly before the moin program
236 name and even to explicitly use the path to that program.
237
238 Recommended Software
239 --------------------
240
241 See the "Dependencies" section below for essential software.
242
243 The moinsetup tool is recommended for installation since it aims to support
244 all versions of MoinMoin that are supported for use with this software.
245
246 See the following page for information on moinsetup:
247
248 http://moinmo.in/ScriptMarket/moinsetup
249
250 The Xapian search software is highly recommended, if not technically
251 essential, for the acceptable performance of the EventAggregator macro since
252 the macro makes use of search routines in MoinMoin that can dominate the time
253 spent processing requests.
254
255 See the following page for information on Xapian and MoinMoin:
256
257 http://moinmo.in/HelpOnXapian
258
259 The vContent software is required for the parsing of iCalendar information
260 from remote event sources.
261
262 See the following page for information on vContent:
263
264 https://hg.boddie.org.uk/vContent
265
266 Troubleshooting: Categories
267 ---------------------------
268
269 See here for a bug related to category recognition:
270
271 http://moinmo.in/MoinMoinBugs/1.7TemplatesNotAppearing
272
273 This affects installations where migrations between versions have occurred,
274 yet the Wiki configuration retains old regular expression details.
275
276 Troubleshooting: Xapian
277 -----------------------
278
279 Xapian can be troublesome, especially where file permissions are concerned: if
280 something acquires a lock on the index (for example, the moin script, possibly
281 invoked via moinsetup) nothing else will be able to modify the index, and this
282 may cause pages to become detached from their categories in the index.
283
284 To resolve index issues, try and run the following command (with the appropriate
285 options):
286
287 moin --config-dir=path-to-wiki --wiki-url=example.com/ index build --mode=rebuild
288
289 It may be necessary to manually remove locks. This can be done as follows:
290
291 find path-to-wiki/data/cache/xapian -depth -name "*lock" -type d -exec rmdir '{}' \;
292
293 Troubleshooting: Plain Text Formatting
294 --------------------------------------
295
296 Plain text formatting is used in certain places in EventAggregator, but the
297 formatter is rather broken in MoinMoin 1.8 and in previous releases. See the
298 following page for a summary:
299
300 http://moinmo.in/FeatureRequests/TextPlainFormatterRewrite
301
302 A patch is supplied in the patches directory to fix link formatting in the
303 plain text formatter, and once copied into the root directory of the MoinMoin
304 1.8 sources it can be applied as follows:
305
306 patch -p1 < patch-plain-text-link-formatting-1.8.diff
307
308 Contact, Copyright and Licence Information
309 ------------------------------------------
310
311 See the following Web pages for more information about this work:
312
313 http://moinmo.in/MacroMarket/EventAggregator
314 http://moinmo.in/ActionMarket/EventAggregator
315
316 The author can be contacted at the following e-mail address:
317
318 paul@boddie.org.uk
319
320 Copyright and licence information can be found in the docs directory - see
321 docs/COPYING.txt and docs/LICENCE.txt for more information.
322
323 Dependencies
324 ------------
325
326 EventAggregator has the following basic dependencies:
327
328 Packages Release Information
329 -------- -------------------
330
331 MoinSupport Tested with 0.2
332 Source: http://hgweb.boddie.org.uk/MoinSupport
333
334 pytz Tested with 2007k (specifically 2007k-0ubuntu2)
335 Source: http://pytz.sourceforge.net/
336
337 If time zone handling is not required, pytz need not be installed, but this
338 may result in iCalendar summaries being produced that provide insufficient
339 time zone information for the correct interpretation of time information in
340 those summaries. Thus, it is highly recommended that pytz be installed.
341
342 New in EventAggregator 0.9 (Changes since EventAggregator 0.8.5)
343 ----------------------------------------------------------------
344
345 * Moved much of the support library to the MoinSupport distribution, thus
346 introducing a dependency on that software.
347 * Added support for in-page updates of the event views so that navigation
348 between days, months and different views does not cause a full-page
349 reload if JavaScript is enabled.
350 * Tidied up the new event form, showing a list of known locations for
351 selection, making the event location affect the chosen time zone/regime if
352 the location is known, and hiding latitude and longitude fields unless an
353 unknown location is to be specified.
354 * The EventLocationsDict or equivalent can now retain time zone/regime
355 information about each location.
356 * Added an event parser that can format special page regions in different
357 ways and support links directly to such regions.
358 * Permitted Wiki markup in the description and location metadata.
359 * Added support for search patterns so that event pages can be obtained
360 through arbitrary searches and do not have to belong to particular
361 categories.
362 * Encoded map location pop-up headings as plain text in order to handle
363 locations specified using Wiki formatting.
364 * Permitted events with map references but without location details to be
365 positioned in maps.
366 * Improved navigation between months and days, and between view modes for
367 both levels of calendar view.
368
369 New in EventAggregator 0.8.5 (Changes since EventAggregator 0.8.4)
370 ------------------------------------------------------------------
371
372 * Fixed iCalendar quoting for newlines in calendar data.
373
374 New in EventAggregator 0.8.4 (Changes since EventAggregator 0.8.3)
375 ------------------------------------------------------------------
376
377 * The calculation of hour and minute offsets for time regimes west of the
378 prime meridian was not producing correct results since the day offset
379 provided by pytz was not being considered in the calculation. Such regimes
380 should now produce the expected (hour, minute) offsets such that events
381 employing these regimes can be positioned correctly on a UTC timescale.
382
383 New in EventAggregator 0.8.3 (Changes since EventAggregator 0.8.2)
384 ------------------------------------------------------------------
385
386 * The end dates defined in events from remote iCalendar event sources were
387 not correctly adjusted when aggregating such events. Thus, events with a
388 day-level resolution will have appeared one day longer in calendars and
389 summaries than was actually specified in the source data. This adjustment
390 has now been introduced.
391
392 New in EventAggregator 0.8.2 (Changes since EventAggregator 0.8.1)
393 ------------------------------------------------------------------
394
395 * Improved the error handling around remote event source data retrieval,
396 introducing handling of missing resources and unsupported content types.
397 * Improved the presentation of download and subscription links, adding
398 webcal: URL links for suitable calendar clients.
399
400 New in EventAggregator 0.8.1 (Changes since EventAggregator 0.8)
401 ----------------------------------------------------------------
402
403 * Changed the EventAggregatorNewEvent action to not save new event pages
404 directly, instead invoking the textual page editor for the page so that
405 the page text can be changed and the page saved without a redundant
406 initial version being created. Cancelling the editing operation will also
407 avoid the creation of unwanted event pages.
408 * Added a page break before each map in the print view, adding a page break
409 after each map to fully isolate unpositioned events on separate pages.
410 * Fixed errors where empty location fields were given in vCalendar events.
411 * Reintroduced event sorting in the list and table views.
412 * Fixed location positioning where some events employing an unknown location
413 do not position that location whereas others do (using "geo" information).
414
415 New in EventAggregator 0.8 (Changes since EventAggregator 0.7.1)
416 ----------------------------------------------------------------
417
418 * Added remote event aggregation with support for iCalendar event sources.
419 * Added support for explicit latitude and longitude event properties.
420 * Added support for decimal latitude and longitude values.
421 * Introduced in-page updates of the new event form, avoiding full-page
422 reloads when editing the initial details of an event.
423
424 New in EventAggregator 0.7.1 (Changes since EventAggregator 0.7)
425 ----------------------------------------------------------------
426
427 * Restored MoinMoin 1.9.x compatibility around WikiDict access.
428
429 New in EventAggregator 0.7 (Changes since EventAggregator 0.6.4)
430 ----------------------------------------------------------------
431
432 * Added a day view which shows events ordered according to their timespans
433 within each day.
434 * Added a map view which shows events according to their location. This
435 requires map images to be uploaded to a designated page, and map locations
436 to be defined on a designated page.
437 * Switched to using moinsetup for the installation procedure.
438 * Introduced formatting of description, location and topic information in
439 the list and table views and in RSS format summaries.
440 * Introduced support for days as calendar period units in the list view.
441 * Added "Help" and "New event" links alongside the calendar view controls,
442 giving the download and view controls centre alignment.
443
444 New in EventAggregator 0.6.4 (Changes since EventAggregator 0.6.3)
445 ------------------------------------------------------------------
446
447 * Fixed pop-up element labels where one limit of a calendar has not been
448 specified.
449
450 New in EventAggregator 0.6.3 (Changes since EventAggregator 0.6.2)
451 ------------------------------------------------------------------
452
453 * Fixed category membership parsing.
454 * Fixed open-ended calendars and their pop-up summaries.
455
456 New in EventAggregator 0.6.2 (Changes since EventAggregator 0.6.1)
457 ------------------------------------------------------------------
458
459 * Fixed HTML encoding in the forms generated by the actions.
460 * Dropped MoinMoin 1.5.x support, since Xapian search is not available for
461 that version and is virtually a necessity.
462 * Fixed form handling to be compatible with MoinMoin 1.9.x, since that
463 particular release series introduced an incompatible request API that
464 breaks existing code (no longer providing access to query string
465 parameters via the form attribute, and only returning single values
466 unless the new getlist method on form-like objects is used).
467 * Fixed the direct writing of requests to be compatible with MoinMoin 1.9.
468 * Added pop-up elements showing information about the calendar/view
469 resources available for download or subscription.
470 * Added download/subscription links which open the form associated with the
471 EventAggregatorSummary action and permit editing of the supplied values.
472
473 New in EventAggregator 0.6.1 (Changes since EventAggregator 0.6)
474 ----------------------------------------------------------------
475
476 * Fixed HTML encoding in the forms generated by the actions.
477
478 New in EventAggregator 0.6 (Changes since EventAggregator 0.5)
479 --------------------------------------------------------------
480
481 * Added print stylesheet rules in order to improve the printed versions of
482 calendars.
483 * Fixed definition list parsing to handle completely empty definitions
484 (having no space after the "::" token) which previously captured text from
485 subsequent lines, and merely empty definitions which previously would have
486 produced a single empty value for definitions providing lists of values.
487 * Added a script to import events from RSS feeds.
488 * Added support for a link entry in event pages, although this does not
489 replace the link information provided by the RSS and iCalendar summaries.
490 * Fixed the production of the summaries when pages with no available edit
491 log information are to be included.
492 * Added support for event times and time zone/regime information. This is
493 subject to revision.
494
495 New in EventAggregator 0.5 (Changes since EventAggregator 0.4)
496 --------------------------------------------------------------
497
498 * Changed the EventAggregatorNewEvent action to substitute only the stated
499 title, not the full page title, into the new page.
500 * Changed event colouring to use the event summary as the basis for
501 calculating the colour used in the calendar. This means that related
502 events can be coloured identically if their summaries are the same.
503 * Added support for multiple events on a single event page.
504 * Introduced EventPage and Event abstractions in order to better support new
505 features.
506 * Introduced basic and advanced modes to the EventAggregatorNewEvent action,
507 along with date swapping to correct cases where the start is given as
508 being later than the end of an event.
509 * Fixed the "download this calendar" and "subscribe to this calendar" links
510 by propagating the "raw" calendar start and end values within the macro.
511 These links should yield events only within the period defined for a
512 calendar, not all events in a calendar's categories. This fix also ensures
513 that the links for year- and month-relative calendars are correct, rather
514 than the specific links generated previously. Thus, a "this year's events"
515 link will now continue to produce a resource with the current year's
516 events, rather than the events from the year when the link was generated.
517
518 New in EventAggregator 0.4 (Changes since EventAggregator 0.3)
519 --------------------------------------------------------------
520
521 * Added a table view in the macro, using special topic/category styles to
522 provide background colours for events.
523 * Added category propagation from calendars to the new event form provided
524 by the EventAggregatorNewEvent action.
525 * Added a default template parameter to the macro, employed by the new event
526 form.
527 * Added a parent page parameter which is used by the new event form to place
528 new event pages in a particular location specific to a calendar or
529 collection of events.
530 * Improved the presentation of pop-up event information elements.
531 * Added navigation between display modes (calendar, list and table views).
532 * Ensured that calendar settings are retained when creating new events for a
533 calendar.
534 * Fixed various problems with events not having topics.
535
536 New in EventAggregator 0.3 (Changes since EventAggregator 0.2)
537 --------------------------------------------------------------
538
539 * Added a parameter to the EventAggregatorSummary action to select the
540 source of event descriptions for the RSS feed.
541 * Updated the documentation to cover the RSS support.
542 * Added the EventAggregatorNewEvent action.
543
544 New in EventAggregator 0.2 (Changes since EventAggregator 0.1)
545 --------------------------------------------------------------
546
547 * Improved the calendar view in the macro to use the fixed table layout
548 algorithm and to provide cells spanning potentially many columns for
549 continuing events. Introduced pop-up elements in order to show truncated
550 event names.
551 * Made the "weekly" naming policy the default in the calendar view.
552 * Improved the list view in the macro.
553 * Introduced RSS 2.0 feed support.
554 * Improved the help pages.
555
556 Release Procedures
557 ------------------
558
559 Update the EventAggregatorSupport.py __version__ attribute and the setup.py
560 version details.
561 Change the version number and package filename/directory in the documentation.
562 Update the setup.py and PKG-INFO files.
563 Update the release notes (see above).
564 Tag, export.
565 Archive, upload.
566 Update the MacroMarket and ActionMarket (see above for the URLs).