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