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