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