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