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