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 CategoryEvent). 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 an iCalendar summary
12 of event data based on pages belonging to specific categories, as described
13 above. The category, start and end parameters are read directly from the
14 request as URL or form parameters.
15
16 Installation
17 ------------
18
19 To install the support library, consider using the setup.py script provided:
20
21 python setup.py install
22
23 You may wish to indicate a specific prefix if MoinMoin is not installed in the
24 traditional location:
25
26 python setup.py install --prefix=path-to-moin-prefix
27
28 To install the macro in a Wiki, consider using the instmacros script provided:
29
30 ./instmacros path-to-wiki
31
32 On non-UNIX platforms, it is necessary to manually copy the contents of the
33 macros directory in this distribution into the macros directory of your Wiki.
34
35 It is highly recommended that the tables and listings be styled according to
36 the stylesheet provided, and you can use this file as a starting point for
37 your own modifications. To install the stylesheet, consider using the
38 insttheme script provided:
39
40 ./insttheme path-to-wiki theme-name
41
42 Again, on non-UNIX platforms, it is necessary to manually copy the files. In
43 this case, just copy the contents of the css directory into the css directory
44 of themes which will support styling of event calendars and listings.
45
46 To activate the styles provided by the stylesheet in the css directory, you
47 will need to edit the screen.css file in each affected theme's css directory,
48 adding the following before any style rules:
49
50 /* Event aggregation... */
51
52 @import "event-aggregator.css";
53
54 This ensures that the styles are made available to the browser.
55
56 To install the action in a Wiki, consider using the instactions script provided:
57
58 ./instactions path-to-wiki
59
60 On non-UNIX platforms, it is necessary to manually copy the contents of the
61 actions directory in this distribution into the actions directory of your Wiki.
62
63 Using the Macro
64 ---------------
65
66 It should now be possible to edit pages and use the macro as follows. For
67 MoinMoin 1.5:
68
69 [[EventAggregator(CategoryEvent)]]
70
71 For MoinMoin 1.6 and above:
72
73 <<EventAggregator(CategoryEvent)>>
74
75 As arguments to the macro, you must indicate a comma-separated list of
76 categories to be inspected for event data. For example:
77
78 <<EventAggregator(CategoryEvent,CategoryTraining)>>
79
80 By default, this should display a calendar in a collection of tables, one for
81 each month containing events. To show a collection of month-by-month listings,
82 use the 'mode' argument as follows:
83
84 <<EventAggregator(CategoryEvent,mode=list)>>
85
86 Using the Action
87 ----------------
88
89 To obtain an iCalendar summary, a collection of parameters can be specified in
90 the URL of any Wiki page. For example:
91
92 http://example.com/moin/FrontPage?action=EventAggregatorSummary&category=CategoryEvents
93
94 This should produce an iCalendar resource in response. By specifying 'start'
95 and 'end' parameters, a restricted view can be obtained. For example:
96
97 http://example.com/moin/FrontPage?action=EventAggregatorSummary&category=CategoryEvents&start=2009-06&end=2009-07
98
99 This would restrict the initial query to events occurring in the months of
100 June 2009 ('2009-06') and July 2009 ('2009-07').
101
102 Recommended Software
103 --------------------
104
105 The Xapian search software is highly recommended, if not technically
106 essential, for the acceptable performance of the EventAggregator macro since
107 the macro makes use of search routines in MoinMoin that can dominate the time
108 spent processing requests.
109
110 See the following page for information on Xapian and MoinMoin:
111
112 http://moinmo.in/HelpOnXapian
113
114 Troubleshooting
115 ---------------
116
117 See here for a bug related to category recognition:
118
119 http://moinmo.in/MoinMoinBugs/1.7TemplatesNotAppearing
120
121 This affects installations where migrations between versions have occurred,
122 yet the Wiki configuration retains old regular expression details.
123
124 Contact, Copyright and Licence Information
125 ------------------------------------------
126
127 See the following Web pages for more information about this work:
128
129 http://moinmo.in/MacroMarket/EventAggregator
130 http://moinmo.in/ActionMarket/EventAggregator
131
132 The author can be contacted at the following e-mail address:
133
134 paul@boddie.org.uk
135
136 Copyright and licence information can be found in the docs directory - see
137 docs/COPYING.txt and docs/LICENCE.txt for more information.
138
139 Release Procedures
140 ------------------
141
142 Update the EventAggregatorSupport.py __version__ attribute.
143 Change the version number and package filename/directory in the documentation.
144 Update the release notes (see above).
145 Tag, export.
146 Archive, upload.
147 Update the MacroMarket and ActionMarket (see above for the URLs).