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.6.4 fixes the download/subscription pop-up elements where calendars
30 are open-ended, this having caused the macro to fail completely when showing
31 such calendars.
32
33 Release 0.6.2 fixes various bugs in HTML production done by the actions. It is
34 strongly recommended to upgrade from earlier versions to this or a later
35 release.
36
37 In release 0.6.2, support for MoinMoin 1.5.x has been dropped. Since usage of
38 the Xapian search software is practically a necessary part of deploying this
39 solution, and yet Xapian only became integrated with MoinMoin from version 1.6
40 onwards, few deployments should have involved MoinMoin 1.5.x.
41
42 In release 0.6, support for event times has been introduced. Due to the
43 complicated nature of times, time zones, time regimes, and so on, the
44 behaviour of the software may change in future versions to support common
45 use-cases in a more convenient fashion. Please be aware that implicitly chosen
46 or generated time or time zone information may change for events, particularly
47 those whose times are ambiguous or ill-defined. It is highly recommended that
48 the pytz library be installed - see the documentation regarding dependencies
49 for more information.
50
51 In release 0.5, the "download this calendar" and "subscribe to this calendar"
52 links have been fixed to return only events within the specified period and to
53 work with day- and month-relative calendars. Users who have bookmarks in their
54 Web browser or feed reader should replace these bookmarks by visiting the
55 bookmarked page and acquiring new versions of these links, once
56 EventAggregator has been upgraded.
57
58 Installation
59 ------------
60
61 To install the support library and MoinMoin-related scripts, consider using
62 the setup.py script provided:
63
64 python setup.py install
65
66 You may wish to indicate a specific prefix if MoinMoin is not installed in the
67 traditional location:
68
69 python setup.py install --prefix=path-to-moin-prefix
70
71 To install the macro in a Wiki, consider using the instmacros script provided:
72
73 ./instmacros path-to-wiki
74
75 On non-UNIX platforms, it is necessary to manually copy the contents of the
76 macros directory in this distribution into the macros directory of your Wiki.
77
78 It is highly recommended that the tables and listings be styled according to
79 the stylesheet provided, and you can use this file as a starting point for
80 your own modifications. To install the stylesheet, consider using the
81 insttheme script provided:
82
83 ./insttheme path-to-wiki theme-name
84
85 Again, on non-UNIX platforms, it is necessary to manually copy the files. In
86 this case, just copy the contents of the css directory into the css directory
87 of themes which will support styling of event calendars and listings.
88
89 To activate the styles provided by the stylesheet in the css directory, you
90 will need to edit the screen.css file in each affected theme's css directory,
91 adding the following before any style rules:
92
93 /* Event aggregation... */
94
95 @import "event-aggregator.css";
96
97 This ensures that the styles are made available to the browser. Additionally,
98 to make sure that printed pages are correctly styled, the following also needs
99 to be added to the print.css file in each affected theme's css directory:
100
101 /* Event aggregation... */
102
103 @import "event-aggregator-print.css";
104 @import "event-aggregator.css";
105
106 To install the actions in a Wiki, consider using the instactions script
107 provided:
108
109 ./instactions path-to-wiki
110
111 On non-UNIX platforms, it is necessary to manually copy the contents of the
112 actions directory in this distribution into the actions directory of your
113 Wiki.
114
115 Useful Pages
116 ------------
117
118 The pages directory contains a selection of useful pages using a syntax
119 appropriate for use with MoinMoin 1.6 or later. These pages can be created
120 through the Wiki and their contents copied in from each of the files.
121
122 Using the Macro
123 ---------------
124
125 It should now be possible to edit pages and use the macro as follows:
126
127 <<EventAggregator(CategoryEvents)>>
128
129 As arguments to the macro, you must indicate a comma-separated list of
130 categories to be inspected for event data. For example:
131
132 <<EventAggregator(CategoryEvents,CategoryTraining)>>
133
134 By default, this should display a calendar in a collection of tables, one for
135 each month containing events. To show a collection of month-by-month listings,
136 use the 'mode' argument as follows:
137
138 <<EventAggregator(CategoryEvents,mode=list)>>
139
140 See pages/HelpOnEventAggregator for more detailed information.
141
142 Using the Actions
143 -----------------
144
145 To obtain an iCalendar summary, the EventAggregatorSummary action can be
146 selected from the actions menu on any page. Alternatively, a collection of
147 parameters can be specified in the URL of any Wiki page.
148
149 See pages/HelpOnEventAggregatorSummary for more detailed information.
150
151 To create new events using the EventAggregatorNewEvent action, the appropriate
152 menu entry can be selected in the actions menu. Alternatively, clicking on a
153 day number in a calendar view will invoke the action and pre-fill the form
154 with the start date set to the selected day from the calendar.
155
156 See pages/HelpOnEventAggregatorNewEvent for more detailed information.
157
158 Running the Scripts
159 -------------------
160
161 To import events from an RSS feed, the eventfeed script integrated with the
162 moin program can be used as follows:
163
164 moin --config-dir=path-to-wiki --wiki-url=example.com/ \
165 import eventfeed --url=url-of-events-feed
166
167 Thus, to import events from the FSFE events RSS feed, the following command
168 could be used:
169
170 moin --config-dir=path-to-wiki --wiki-url=example.com/ \
171 import eventfeed --url=http://www.fsfe.org/events/events.en.rss
172
173 If this command is being used with sudo, make sure to use the -u option so
174 that the script can operate as the appropriate user. For example:
175
176 sudo -u www-data moin --config-dir=path-to-wiki --wiki-url=example.com/ \
177 import eventfeed --url=http://www.fsfe.org/events/events.en.rss
178
179 It may also be necessary to set PYTHONPATH directly before the moin program
180 name and even to explicitly use the path to that program.
181
182 Recommended Software
183 --------------------
184
185 The Xapian search software is highly recommended, if not technically
186 essential, for the acceptable performance of the EventAggregator macro since
187 the macro makes use of search routines in MoinMoin that can dominate the time
188 spent processing requests.
189
190 See the following page for information on Xapian and MoinMoin:
191
192 http://moinmo.in/HelpOnXapian
193
194 Troubleshooting
195 ---------------
196
197 See here for a bug related to category recognition:
198
199 http://moinmo.in/MoinMoinBugs/1.7TemplatesNotAppearing
200
201 This affects installations where migrations between versions have occurred,
202 yet the Wiki configuration retains old regular expression details.
203
204 Contact, Copyright and Licence Information
205 ------------------------------------------
206
207 See the following Web pages for more information about this work:
208
209 http://moinmo.in/MacroMarket/EventAggregator
210 http://moinmo.in/ActionMarket/EventAggregator
211
212 The author can be contacted at the following e-mail address:
213
214 paul@boddie.org.uk
215
216 Copyright and licence information can be found in the docs directory - see
217 docs/COPYING.txt and docs/LICENCE.txt for more information.
218
219 Dependencies
220 ------------
221
222 EventAggregator has the following basic dependencies:
223
224 Packages Release Information
225 -------- -------------------
226
227 pytz Tested with 2007k (specifically 2007k-0ubuntu2)
228 Source: http://pytz.sourceforge.net/
229
230 If time zone handling is not required, pytz need not be installed, but this
231 may result in iCalendar summaries being produced that provide insufficient
232 time zone information for the correct interpretation of time information in
233 those summaries. Thus, it is highly recommended that pytz be installed.
234
235 New in EventAggregator 0.6.4 (Changes since EventAggregator 0.6.3)
236 ------------------------------------------------------------------
237
238 * Fixed pop-up element labels where one limit of a calendar has not been
239 specified.
240
241 New in EventAggregator 0.6.3 (Changes since EventAggregator 0.6.2)
242 ------------------------------------------------------------------
243
244 * Fixed category membership parsing.
245 * Fixed open-ended calendars and their pop-up summaries.
246
247 New in EventAggregator 0.6.2 (Changes since EventAggregator 0.6.1)
248 ------------------------------------------------------------------
249
250 * Dropped MoinMoin 1.5.x support, since Xapian search is not available for
251 that version and is virtually a necessity.
252 * Fixed form handling to be compatible with MoinMoin 1.9.x, since that
253 particular release series introduced an incompatible request API that
254 breaks existing code (no longer providing access to query string
255 parameters via the form attribute, and only returning single values
256 unless the new getlist method on form-like objects is used).
257 * Fixed the direct writing of requests to be compatible with MoinMoin 1.9.
258 * Added pop-up elements showing information about the calendar/view
259 resources available for download or subscription.
260 * Added download/subscription links which open the form associated with the
261 EventAggregatorSummary action and permit editing of the supplied values.
262
263 New in EventAggregator 0.6.1 (Changes since EventAggregator 0.6)
264 ----------------------------------------------------------------
265
266 * Fixed HTML encoding in the forms generated by the actions.
267
268 New in EventAggregator 0.6 (Changes since EventAggregator 0.5)
269 --------------------------------------------------------------
270
271 * Added print stylesheet rules in order to improve the printed versions of
272 calendars.
273 * Fixed definition list parsing to handle completely empty definitions
274 (having no space after the "::" token) which previously captured text from
275 subsequent lines, and merely empty definitions which previously would have
276 produced a single empty value for definitions providing lists of values.
277 * Added a script to import events from RSS feeds.
278 * Added support for a link entry in event pages, although this does not
279 replace the link information provided by the RSS and iCalendar summaries.
280 * Fixed the production of the summaries when pages with no available edit
281 log information are to be included.
282 * Added support for event times and time zone/regime information. This is
283 subject to revision.
284
285 New in EventAggregator 0.5 (Changes since EventAggregator 0.4)
286 --------------------------------------------------------------
287
288 * Changed the EventAggregatorNewEvent action to substitute only the stated
289 title, not the full page title, into the new page.
290 * Changed event colouring to use the event summary as the basis for
291 calculating the colour used in the calendar. This means that related
292 events can be coloured identically if their summaries are the same.
293 * Added support for multiple events on a single event page.
294 * Introduced EventPage and Event abstractions in order to better support new
295 features.
296 * Introduced basic and advanced modes to the EventAggregatorNewEvent action,
297 along with date swapping to correct cases where the start is given as
298 being later than the end of an event.
299 * Fixed the "download this calendar" and "subscribe to this calendar" links
300 by propagating the "raw" calendar start and end values within the macro.
301 These links should yield events only within the period defined for a
302 calendar, not all events in a calendar's categories. This fix also ensures
303 that the links for year- and month-relative calendars are correct, rather
304 than the specific links generated previously. Thus, a "this year's events"
305 link will now continue to produce a resource with the current year's
306 events, rather than the events from the year when the link was generated.
307
308 New in EventAggregator 0.4 (Changes since EventAggregator 0.3)
309 --------------------------------------------------------------
310
311 * Added a table view in the macro, using special topic/category styles to
312 provide background colours for events.
313 * Added category propagation from calendars to the new event form provided
314 by the EventAggregatorNewEvent action.
315 * Added a default template parameter to the macro, employed by the new event
316 form.
317 * Added a parent page parameter which is used by the new event form to place
318 new event pages in a particular location specific to a calendar or
319 collection of events.
320 * Improved the presentation of pop-up event information elements.
321 * Added navigation between display modes (calendar, list and table views).
322 * Ensured that calendar settings are retained when creating new events for a
323 calendar.
324 * Fixed various problems with events not having topics.
325
326 New in EventAggregator 0.3 (Changes since EventAggregator 0.2)
327 --------------------------------------------------------------
328
329 * Added a parameter to the EventAggregatorSummary action to select the
330 source of event descriptions for the RSS feed.
331 * Updated the documentation to cover the RSS support.
332 * Added the EventAggregatorNewEvent action.
333
334 New in EventAggregator 0.2 (Changes since EventAggregator 0.1)
335 --------------------------------------------------------------
336
337 * Improved the calendar view in the macro to use the fixed table layout
338 algorithm and to provide cells spanning potentially many columns for
339 continuing events. Introduced pop-up elements in order to show truncated
340 event names.
341 * Made the "weekly" naming policy the default in the calendar view.
342 * Improved the list view in the macro.
343 * Introduced RSS 2.0 feed support.
344 * Improved the help pages.
345
346 Release Procedures
347 ------------------
348
349 Update the EventAggregatorSupport.py __version__ attribute and the setup.py
350 version details.
351 Change the version number and package filename/directory in the documentation.
352 Update the setup.py and PKG-INFO files.
353 Update the release notes (see above).
354 Tag, export.
355 Archive, upload.
356 Update the MacroMarket and ActionMarket (see above for the URLs).