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