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
178 New in EventAggregator 0.5 (Changes since EventAggregator 0.4)
179 --------------------------------------------------------------
180
181 * Changed the EventAggregatorNewEvent action to substitute only the stated
182 title, not the full page title, into the new page.
183 * Changed event colouring to use the event summary as the basis for
184 calculating the colour used in the calendar. This means that related
185 events can be coloured identically if their summaries are the same.
186 * Added support for multiple events on a single event page.
187 * Introduced EventPage and Event abstractions in order to better support new
188 features.
189 * Introduced basic and advanced modes to the EventAggregatorNewEvent action,
190 along with date swapping to correct cases where the start is given as
191 being later than the end of an event.
192 * Fixed the "download this calendar" and "subscribe to this calendar" links
193 by propagating the "raw" calendar start and end values within the macro.
194 These links should yield events only within the period defined for a
195 calendar, not all events in a calendar's categories. This fix also ensures
196 that the links for year- and month-relative calendars are correct, rather
197 than the specific links generated previously. Thus, a "this year's events"
198 link will now continue to produce a resource with the current year's
199 events, rather than the events from the year when the link was generated.
200
201 New in EventAggregator 0.4 (Changes since EventAggregator 0.3)
202 --------------------------------------------------------------
203
204 * Added a table view in the macro, using special topic/category styles to
205 provide background colours for events.
206 * Added category propagation from calendars to the new event form provided
207 by the EventAggregatorNewEvent action.
208 * Added a default template parameter to the macro, employed by the new event
209 form.
210 * Added a parent page parameter which is used by the new event form to place
211 new event pages in a particular location specific to a calendar or
212 collection of events.
213 * Improved the presentation of pop-up event information elements.
214 * Added navigation between display modes (calendar, list and table views).
215 * Ensured that calendar settings are retained when creating new events for a
216 calendar.
217 * Fixed various problems with events not having topics.
218
219 New in EventAggregator 0.3 (Changes since EventAggregator 0.2)
220 --------------------------------------------------------------
221
222 * Added a parameter to the EventAggregatorSummary action to select the
223 source of event descriptions for the RSS feed.
224 * Updated the documentation to cover the RSS support.
225 * Added the EventAggregatorNewEvent action.
226
227 New in EventAggregator 0.2 (Changes since EventAggregator 0.1)
228 --------------------------------------------------------------
229
230 * Improved the calendar view in the macro to use the fixed table layout
231 algorithm and to provide cells spanning potentially many columns for
232 continuing events. Introduced pop-up elements in order to show truncated
233 event names.
234 * Made the "weekly" naming policy the default in the calendar view.
235 * Improved the list view in the macro.
236 * Introduced RSS 2.0 feed support.
237 * Improved the help pages.
238
239 Release Procedures
240 ------------------
241
242 Update the EventAggregatorSupport.py __version__ attribute and the setup.py
243 version details.
244 Change the version number and package filename/directory in the documentation.
245 Update the setup.py and PKG-INFO files.
246 Update the release notes (see above).
247 Tag, export.
248 Archive, upload.
249 Update the MacroMarket and ActionMarket (see above for the URLs).