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.
72
73 To install the actions in a Wiki, consider using the instactions script provided:
74
75 ./instactions path-to-wiki
76
77 On non-UNIX platforms, it is necessary to manually copy the contents of the
78 actions directory in this distribution into the actions directory of your Wiki.
79
80 Useful Pages
81 ------------
82
83 The pages directory contains a selection of useful pages using a syntax
84 appropriate for use with MoinMoin 1.6 or later. These pages can be created
85 through the Wiki and their contents copied in from each of the files.
86
87 Using the Macro
88 ---------------
89
90 It should now be possible to edit pages and use the macro as follows. For
91 MoinMoin 1.5:
92
93 [[EventAggregator(CategoryEvents)]]
94
95 For MoinMoin 1.6 and above:
96
97 <<EventAggregator(CategoryEvents)>>
98
99 As arguments to the macro, you must indicate a comma-separated list of
100 categories to be inspected for event data. For example:
101
102 <<EventAggregator(CategoryEvents,CategoryTraining)>>
103
104 By default, this should display a calendar in a collection of tables, one for
105 each month containing events. To show a collection of month-by-month listings,
106 use the 'mode' argument as follows:
107
108 <<EventAggregator(CategoryEvents,mode=list)>>
109
110 See pages/HelpOnEventAggregator for more detailed information.
111
112 Using the Actions
113 -----------------
114
115 To obtain an iCalendar summary, the EventAggregatorSummary action can be
116 selected from the actions menu on any page. Alternatively, a collection of
117 parameters can be specified in the URL of any Wiki page.
118
119 See pages/HelpOnEventAggregatorSummary for more detailed information.
120
121 To create new events using the EventAggregatorNewEvent action, the appropriate
122 menu entry can be selected in the actions menu. Alternatively, clicking on a
123 day number in a calendar view will invoke the action and pre-fill the form
124 with the start date set to the selected day from the calendar.
125
126 See pages/HelpOnEventAggregatorNewEvent for more detailed information.
127
128 Recommended Software
129 --------------------
130
131 The Xapian search software is highly recommended, if not technically
132 essential, for the acceptable performance of the EventAggregator macro since
133 the macro makes use of search routines in MoinMoin that can dominate the time
134 spent processing requests.
135
136 See the following page for information on Xapian and MoinMoin:
137
138 http://moinmo.in/HelpOnXapian
139
140 Troubleshooting
141 ---------------
142
143 See here for a bug related to category recognition:
144
145 http://moinmo.in/MoinMoinBugs/1.7TemplatesNotAppearing
146
147 This affects installations where migrations between versions have occurred,
148 yet the Wiki configuration retains old regular expression details.
149
150 Contact, Copyright and Licence Information
151 ------------------------------------------
152
153 See the following Web pages for more information about this work:
154
155 http://moinmo.in/MacroMarket/EventAggregator
156 http://moinmo.in/ActionMarket/EventAggregator
157
158 The author can be contacted at the following e-mail address:
159
160 paul@boddie.org.uk
161
162 Copyright and licence information can be found in the docs directory - see
163 docs/COPYING.txt and docs/LICENCE.txt for more information.
164
165 New in EventAggregator 0.5 (Changes since EventAggregator 0.4)
166 --------------------------------------------------------------
167
168 * Changed the EventAggregatorNewEvent action to substitute only the stated
169 title, not the full page title, into the new page.
170 * Changed event colouring to use the event summary as the basis for
171 calculating the colour used in the calendar. This means that related
172 events can be coloured identically if their summaries are the same.
173 * Added support for multiple events on a single event page.
174 * Introduced EventPage and Event abstractions in order to better support new
175 features.
176 * Introduced basic and advanced modes to the EventAggregatorNewEvent action,
177 along with date swapping to correct cases where the start is given as
178 being later than the end of an event.
179 * Fixed the "download this calendar" and "subscribe to this calendar" links
180 by propagating the "raw" calendar start and end values within the macro.
181 These links should yield events only within the period defined for a
182 calendar, not all events in a calendar's categories. This fix also ensures
183 that the links for year- and month-relative calendars are correct, rather
184 than the specific links generated previously. Thus, a "this year's events"
185 link will now continue to produce a resource with the current year's
186 events, rather than the events from the year when the link was generated.
187
188 New in EventAggregator 0.4 (Changes since EventAggregator 0.3)
189 --------------------------------------------------------------
190
191 * Added a table view in the macro, using special topic/category styles to
192 provide background colours for events.
193 * Added category propagation from calendars to the new event form provided
194 by the EventAggregatorNewEvent action.
195 * Added a default template parameter to the macro, employed by the new event
196 form.
197 * Added a parent page parameter which is used by the new event form to place
198 new event pages in a particular location specific to a calendar or
199 collection of events.
200 * Improved the presentation of pop-up event information elements.
201 * Added navigation between display modes (calendar, list and table views).
202 * Ensured that calendar settings are retained when creating new events for a
203 calendar.
204 * Fixed various problems with events not having topics.
205
206 New in EventAggregator 0.3 (Changes since EventAggregator 0.2)
207 --------------------------------------------------------------
208
209 * Added a parameter to the EventAggregatorSummary action to select the
210 source of event descriptions for the RSS feed.
211 * Updated the documentation to cover the RSS support.
212 * Added the EventAggregatorNewEvent action.
213
214 New in EventAggregator 0.2 (Changes since EventAggregator 0.1)
215 --------------------------------------------------------------
216
217 * Improved the calendar view in the macro to use the fixed table layout
218 algorithm and to provide cells spanning potentially many columns for
219 continuing events. Introduced pop-up elements in order to show truncated
220 event names.
221 * Made the "weekly" naming policy the default in the calendar view.
222 * Improved the list view in the macro.
223 * Introduced RSS 2.0 feed support.
224 * Improved the help pages.
225
226 Release Procedures
227 ------------------
228
229 Update the EventAggregatorSupport.py __version__ attribute and the setup.py
230 version details.
231 Change the version number and package filename/directory in the documentation.
232 Update the setup.py and PKG-INFO files.
233 Update the release notes (see above).
234 Tag, export.
235 Archive, upload.
236 Update the MacroMarket and ActionMarket (see above for the URLs).