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