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