paul@6 | 1 | Introduction
|
paul@6 | 2 | ------------
|
paul@6 | 3 |
|
paul@6 | 4 | The EventAggregator macro for MoinMoin can be used to display event calendars
|
paul@6 | 5 | or listings which obtain their data from pages belonging to specific
|
paul@20 | 6 | categories (such as CategoryEvents). The start and end dates are read from the
|
paul@6 | 7 | page describing each event, and the calendar is automatically filled out with
|
paul@6 | 8 | the details of each event, colouring each event period in a specially
|
paul@6 | 9 | generated colour.
|
paul@6 | 10 |
|
paul@44 | 11 | The EventAggregatorSummary action can be used to provide iCalendar and RSS
|
paul@44 | 12 | summaries of event data based on pages belonging to specific categories, as
|
paul@44 | 13 | described above. The category, start and end parameters are read directly from
|
paul@44 | 14 | the request as URL or form parameters: these restrict the extent of each
|
paul@44 | 15 | generated summary.
|
paul@10 | 16 |
|
paul@47 | 17 | The EventAggregatorNewEvent action can be used to conveniently create new
|
paul@47 | 18 | event pages, displaying a simple form which can be filled out in order to
|
paul@47 | 19 | provide elementary event details such as the event title or summary, the
|
paul@47 | 20 | categories to which the page will be assigned, and the start and end dates of
|
paul@47 | 21 | the event.
|
paul@47 | 22 |
|
paul@88 | 23 | The eventfeed script can be used to import events from RSS feeds, inserting
|
paul@88 | 24 | new pages into a Wiki.
|
paul@88 | 25 |
|
paul@80 | 26 | Important Notices
|
paul@80 | 27 | -----------------
|
paul@80 | 28 |
|
paul@176 | 29 | Release 0.6.4 fixes the download/subscription pop-up elements where calendars
|
paul@176 | 30 | are open-ended, this having caused the macro to fail completely when showing
|
paul@176 | 31 | such calendars.
|
paul@176 | 32 |
|
paul@148 | 33 | Release 0.6.2 fixes various bugs in HTML production done by the actions. It is
|
paul@164 | 34 | strongly recommended to upgrade from earlier versions to this or a later
|
paul@164 | 35 | release.
|
paul@137 | 36 |
|
paul@148 | 37 | In release 0.6.2, support for MoinMoin 1.5.x has been dropped. Since usage of
|
paul@117 | 38 | the Xapian search software is practically a necessary part of deploying this
|
paul@117 | 39 | solution, and yet Xapian only became integrated with MoinMoin from version 1.6
|
paul@117 | 40 | onwards, few deployments should have involved MoinMoin 1.5.x.
|
paul@117 | 41 |
|
paul@102 | 42 | In release 0.6, support for event times has been introduced. Due to the
|
paul@102 | 43 | complicated nature of times, time zones, time regimes, and so on, the
|
paul@102 | 44 | behaviour of the software may change in future versions to support common
|
paul@102 | 45 | use-cases in a more convenient fashion. Please be aware that implicitly chosen
|
paul@102 | 46 | or generated time or time zone information may change for events, particularly
|
paul@106 | 47 | those whose times are ambiguous or ill-defined. It is highly recommended that
|
paul@106 | 48 | the pytz library be installed - see the documentation regarding dependencies
|
paul@106 | 49 | for more information.
|
paul@102 | 50 |
|
paul@80 | 51 | In release 0.5, the "download this calendar" and "subscribe to this calendar"
|
paul@80 | 52 | links have been fixed to return only events within the specified period and to
|
paul@80 | 53 | work with day- and month-relative calendars. Users who have bookmarks in their
|
paul@80 | 54 | Web browser or feed reader should replace these bookmarks by visiting the
|
paul@88 | 55 | bookmarked page and acquiring new versions of these links, once
|
paul@88 | 56 | EventAggregator has been upgraded.
|
paul@80 | 57 |
|
paul@6 | 58 | Installation
|
paul@6 | 59 | ------------
|
paul@6 | 60 |
|
paul@90 | 61 | To install the support library and MoinMoin-related scripts, consider using
|
paul@90 | 62 | the setup.py script provided:
|
paul@10 | 63 |
|
paul@10 | 64 | python setup.py install
|
paul@10 | 65 |
|
paul@10 | 66 | You may wish to indicate a specific prefix if MoinMoin is not installed in the
|
paul@10 | 67 | traditional location:
|
paul@10 | 68 |
|
paul@10 | 69 | python setup.py install --prefix=path-to-moin-prefix
|
paul@10 | 70 |
|
paul@6 | 71 | To install the macro in a Wiki, consider using the instmacros script provided:
|
paul@6 | 72 |
|
paul@6 | 73 | ./instmacros path-to-wiki
|
paul@6 | 74 |
|
paul@6 | 75 | On non-UNIX platforms, it is necessary to manually copy the contents of the
|
paul@6 | 76 | macros directory in this distribution into the macros directory of your Wiki.
|
paul@6 | 77 |
|
paul@10 | 78 | It is highly recommended that the tables and listings be styled according to
|
paul@10 | 79 | the stylesheet provided, and you can use this file as a starting point for
|
paul@10 | 80 | your own modifications. To install the stylesheet, consider using the
|
paul@10 | 81 | insttheme script provided:
|
paul@10 | 82 |
|
paul@10 | 83 | ./insttheme path-to-wiki theme-name
|
paul@10 | 84 |
|
paul@10 | 85 | Again, on non-UNIX platforms, it is necessary to manually copy the files. In
|
paul@10 | 86 | this case, just copy the contents of the css directory into the css directory
|
paul@10 | 87 | of themes which will support styling of event calendars and listings.
|
paul@10 | 88 |
|
paul@10 | 89 | To activate the styles provided by the stylesheet in the css directory, you
|
paul@10 | 90 | will need to edit the screen.css file in each affected theme's css directory,
|
paul@10 | 91 | adding the following before any style rules:
|
paul@10 | 92 |
|
paul@10 | 93 | /* Event aggregation... */
|
paul@10 | 94 |
|
paul@10 | 95 | @import "event-aggregator.css";
|
paul@10 | 96 |
|
paul@82 | 97 | This ensures that the styles are made available to the browser. Additionally,
|
paul@82 | 98 | to make sure that printed pages are correctly styled, the following also needs
|
paul@82 | 99 | to be added to the print.css file in each affected theme's css directory:
|
paul@82 | 100 |
|
paul@82 | 101 | /* Event aggregation... */
|
paul@82 | 102 |
|
paul@82 | 103 | @import "event-aggregator-print.css";
|
paul@82 | 104 | @import "event-aggregator.css";
|
paul@10 | 105 |
|
paul@88 | 106 | To install the actions in a Wiki, consider using the instactions script
|
paul@88 | 107 | provided:
|
paul@10 | 108 |
|
paul@10 | 109 | ./instactions path-to-wiki
|
paul@10 | 110 |
|
paul@10 | 111 | On non-UNIX platforms, it is necessary to manually copy the contents of the
|
paul@88 | 112 | actions directory in this distribution into the actions directory of your
|
paul@88 | 113 | Wiki.
|
paul@88 | 114 |
|
paul@27 | 115 | Useful Pages
|
paul@27 | 116 | ------------
|
paul@27 | 117 |
|
paul@27 | 118 | The pages directory contains a selection of useful pages using a syntax
|
paul@27 | 119 | appropriate for use with MoinMoin 1.6 or later. These pages can be created
|
paul@27 | 120 | through the Wiki and their contents copied in from each of the files.
|
paul@27 | 121 |
|
paul@10 | 122 | Using the Macro
|
paul@10 | 123 | ---------------
|
paul@10 | 124 |
|
paul@117 | 125 | It should now be possible to edit pages and use the macro as follows:
|
paul@6 | 126 |
|
paul@20 | 127 | <<EventAggregator(CategoryEvents)>>
|
paul@6 | 128 |
|
paul@6 | 129 | As arguments to the macro, you must indicate a comma-separated list of
|
paul@6 | 130 | categories to be inspected for event data. For example:
|
paul@6 | 131 |
|
paul@20 | 132 | <<EventAggregator(CategoryEvents,CategoryTraining)>>
|
paul@6 | 133 |
|
paul@6 | 134 | By default, this should display a calendar in a collection of tables, one for
|
paul@6 | 135 | each month containing events. To show a collection of month-by-month listings,
|
paul@6 | 136 | use the 'mode' argument as follows:
|
paul@6 | 137 |
|
paul@20 | 138 | <<EventAggregator(CategoryEvents,mode=list)>>
|
paul@20 | 139 |
|
paul@20 | 140 | See pages/HelpOnEventAggregator for more detailed information.
|
paul@6 | 141 |
|
paul@47 | 142 | Using the Actions
|
paul@47 | 143 | -----------------
|
paul@6 | 144 |
|
paul@20 | 145 | To obtain an iCalendar summary, the EventAggregatorSummary action can be
|
paul@20 | 146 | selected from the actions menu on any page. Alternatively, a collection of
|
paul@24 | 147 | parameters can be specified in the URL of any Wiki page.
|
paul@6 | 148 |
|
paul@24 | 149 | See pages/HelpOnEventAggregatorSummary for more detailed information.
|
paul@6 | 150 |
|
paul@47 | 151 | To create new events using the EventAggregatorNewEvent action, the appropriate
|
paul@47 | 152 | menu entry can be selected in the actions menu. Alternatively, clicking on a
|
paul@47 | 153 | day number in a calendar view will invoke the action and pre-fill the form
|
paul@47 | 154 | with the start date set to the selected day from the calendar.
|
paul@47 | 155 |
|
paul@47 | 156 | See pages/HelpOnEventAggregatorNewEvent for more detailed information.
|
paul@47 | 157 |
|
paul@88 | 158 | Running the Scripts
|
paul@88 | 159 | -------------------
|
paul@88 | 160 |
|
paul@88 | 161 | To import events from an RSS feed, the eventfeed script integrated with the
|
paul@88 | 162 | moin program can be used as follows:
|
paul@88 | 163 |
|
paul@88 | 164 | moin --config-dir=path-to-wiki --wiki-url=example.com/ \
|
paul@88 | 165 | import eventfeed --url=url-of-events-feed
|
paul@88 | 166 |
|
paul@88 | 167 | Thus, to import events from the FSFE events RSS feed, the following command
|
paul@88 | 168 | could be used:
|
paul@88 | 169 |
|
paul@88 | 170 | moin --config-dir=path-to-wiki --wiki-url=example.com/ \
|
paul@88 | 171 | import eventfeed --url=http://www.fsfe.org/events/events.en.rss
|
paul@88 | 172 |
|
paul@88 | 173 | If this command is being used with sudo, make sure to use the -u option so
|
paul@88 | 174 | that the script can operate as the appropriate user. For example:
|
paul@88 | 175 |
|
paul@88 | 176 | sudo -u www-data moin --config-dir=path-to-wiki --wiki-url=example.com/ \
|
paul@88 | 177 | import eventfeed --url=http://www.fsfe.org/events/events.en.rss
|
paul@88 | 178 |
|
paul@88 | 179 | It may also be necessary to set PYTHONPATH directly before the moin program
|
paul@88 | 180 | name and even to explicitly use the path to that program.
|
paul@88 | 181 |
|
paul@6 | 182 | Recommended Software
|
paul@6 | 183 | --------------------
|
paul@6 | 184 |
|
paul@6 | 185 | The Xapian search software is highly recommended, if not technically
|
paul@6 | 186 | essential, for the acceptable performance of the EventAggregator macro since
|
paul@6 | 187 | the macro makes use of search routines in MoinMoin that can dominate the time
|
paul@6 | 188 | spent processing requests.
|
paul@6 | 189 |
|
paul@6 | 190 | See the following page for information on Xapian and MoinMoin:
|
paul@6 | 191 |
|
paul@6 | 192 | http://moinmo.in/HelpOnXapian
|
paul@6 | 193 |
|
paul@6 | 194 | Troubleshooting
|
paul@6 | 195 | ---------------
|
paul@6 | 196 |
|
paul@6 | 197 | See here for a bug related to category recognition:
|
paul@6 | 198 |
|
paul@6 | 199 | http://moinmo.in/MoinMoinBugs/1.7TemplatesNotAppearing
|
paul@6 | 200 |
|
paul@6 | 201 | This affects installations where migrations between versions have occurred,
|
paul@6 | 202 | yet the Wiki configuration retains old regular expression details.
|
paul@6 | 203 |
|
paul@6 | 204 | Contact, Copyright and Licence Information
|
paul@6 | 205 | ------------------------------------------
|
paul@6 | 206 |
|
paul@10 | 207 | See the following Web pages for more information about this work:
|
paul@6 | 208 |
|
paul@6 | 209 | http://moinmo.in/MacroMarket/EventAggregator
|
paul@10 | 210 | http://moinmo.in/ActionMarket/EventAggregator
|
paul@6 | 211 |
|
paul@6 | 212 | The author can be contacted at the following e-mail address:
|
paul@6 | 213 |
|
paul@6 | 214 | paul@boddie.org.uk
|
paul@6 | 215 |
|
paul@6 | 216 | Copyright and licence information can be found in the docs directory - see
|
paul@6 | 217 | docs/COPYING.txt and docs/LICENCE.txt for more information.
|
paul@6 | 218 |
|
paul@106 | 219 | Dependencies
|
paul@106 | 220 | ------------
|
paul@106 | 221 |
|
paul@106 | 222 | EventAggregator has the following basic dependencies:
|
paul@106 | 223 |
|
paul@106 | 224 | Packages Release Information
|
paul@106 | 225 | -------- -------------------
|
paul@106 | 226 |
|
paul@106 | 227 | pytz Tested with 2007k (specifically 2007k-0ubuntu2)
|
paul@106 | 228 | Source: http://pytz.sourceforge.net/
|
paul@106 | 229 |
|
paul@106 | 230 | If time zone handling is not required, pytz need not be installed, but this
|
paul@106 | 231 | may result in iCalendar summaries being produced that provide insufficient
|
paul@106 | 232 | time zone information for the correct interpretation of time information in
|
paul@106 | 233 | those summaries. Thus, it is highly recommended that pytz be installed.
|
paul@106 | 234 |
|
paul@173 | 235 | New in EventAggregator 0.6.4 (Changes since EventAggregator 0.6.3)
|
paul@173 | 236 | ------------------------------------------------------------------
|
paul@173 | 237 |
|
paul@173 | 238 | * Fixed pop-up element labels where one limit of a calendar has not been
|
paul@173 | 239 | specified.
|
paul@173 | 240 |
|
paul@164 | 241 | New in EventAggregator 0.6.3 (Changes since EventAggregator 0.6.2)
|
paul@164 | 242 | ------------------------------------------------------------------
|
paul@164 | 243 |
|
paul@164 | 244 | * Fixed category membership parsing.
|
paul@164 | 245 | * Fixed open-ended calendars and their pop-up summaries.
|
paul@164 | 246 |
|
paul@148 | 247 | New in EventAggregator 0.6.2 (Changes since EventAggregator 0.6.1)
|
paul@148 | 248 | ------------------------------------------------------------------
|
paul@109 | 249 |
|
paul@117 | 250 | * Dropped MoinMoin 1.5.x support, since Xapian search is not available for
|
paul@117 | 251 | that version and is virtually a necessity.
|
paul@109 | 252 | * Fixed form handling to be compatible with MoinMoin 1.9.x, since that
|
paul@109 | 253 | particular release series introduced an incompatible request API that
|
paul@109 | 254 | breaks existing code (no longer providing access to query string
|
paul@109 | 255 | parameters via the form attribute, and only returning single values
|
paul@109 | 256 | unless the new getlist method on form-like objects is used).
|
paul@110 | 257 | * Fixed the direct writing of requests to be compatible with MoinMoin 1.9.
|
paul@113 | 258 | * Added pop-up elements showing information about the calendar/view
|
paul@113 | 259 | resources available for download or subscription.
|
paul@113 | 260 | * Added download/subscription links which open the form associated with the
|
paul@113 | 261 | EventAggregatorSummary action and permit editing of the supplied values.
|
paul@109 | 262 |
|
paul@137 | 263 | New in EventAggregator 0.6.1 (Changes since EventAggregator 0.6)
|
paul@137 | 264 | ----------------------------------------------------------------
|
paul@137 | 265 |
|
paul@137 | 266 | * Fixed HTML encoding in the forms generated by the actions.
|
paul@137 | 267 |
|
paul@82 | 268 | New in EventAggregator 0.6 (Changes since EventAggregator 0.5)
|
paul@82 | 269 | --------------------------------------------------------------
|
paul@82 | 270 |
|
paul@82 | 271 | * Added print stylesheet rules in order to improve the printed versions of
|
paul@82 | 272 | calendars.
|
paul@84 | 273 | * Fixed definition list parsing to handle completely empty definitions
|
paul@84 | 274 | (having no space after the "::" token) which previously captured text from
|
paul@84 | 275 | subsequent lines, and merely empty definitions which previously would have
|
paul@84 | 276 | produced a single empty value for definitions providing lists of values.
|
paul@88 | 277 | * Added a script to import events from RSS feeds.
|
paul@88 | 278 | * Added support for a link entry in event pages, although this does not
|
paul@88 | 279 | replace the link information provided by the RSS and iCalendar summaries.
|
paul@89 | 280 | * Fixed the production of the summaries when pages with no available edit
|
paul@89 | 281 | log information are to be included.
|
paul@102 | 282 | * Added support for event times and time zone/regime information. This is
|
paul@102 | 283 | subject to revision.
|
paul@82 | 284 |
|
paul@65 | 285 | New in EventAggregator 0.5 (Changes since EventAggregator 0.4)
|
paul@65 | 286 | --------------------------------------------------------------
|
paul@65 | 287 |
|
paul@65 | 288 | * Changed the EventAggregatorNewEvent action to substitute only the stated
|
paul@65 | 289 | title, not the full page title, into the new page.
|
paul@66 | 290 | * Changed event colouring to use the event summary as the basis for
|
paul@66 | 291 | calculating the colour used in the calendar. This means that related
|
paul@66 | 292 | events can be coloured identically if their summaries are the same.
|
paul@71 | 293 | * Added support for multiple events on a single event page.
|
paul@71 | 294 | * Introduced EventPage and Event abstractions in order to better support new
|
paul@71 | 295 | features.
|
paul@78 | 296 | * Introduced basic and advanced modes to the EventAggregatorNewEvent action,
|
paul@78 | 297 | along with date swapping to correct cases where the start is given as
|
paul@78 | 298 | being later than the end of an event.
|
paul@77 | 299 | * Fixed the "download this calendar" and "subscribe to this calendar" links
|
paul@77 | 300 | by propagating the "raw" calendar start and end values within the macro.
|
paul@77 | 301 | These links should yield events only within the period defined for a
|
paul@77 | 302 | calendar, not all events in a calendar's categories. This fix also ensures
|
paul@77 | 303 | that the links for year- and month-relative calendars are correct, rather
|
paul@77 | 304 | than the specific links generated previously. Thus, a "this year's events"
|
paul@77 | 305 | link will now continue to produce a resource with the current year's
|
paul@77 | 306 | events, rather than the events from the year when the link was generated.
|
paul@65 | 307 |
|
paul@51 | 308 | New in EventAggregator 0.4 (Changes since EventAggregator 0.3)
|
paul@51 | 309 | --------------------------------------------------------------
|
paul@51 | 310 |
|
paul@51 | 311 | * Added a table view in the macro, using special topic/category styles to
|
paul@51 | 312 | provide background colours for events.
|
paul@56 | 313 | * Added category propagation from calendars to the new event form provided
|
paul@56 | 314 | by the EventAggregatorNewEvent action.
|
paul@56 | 315 | * Added a default template parameter to the macro, employed by the new event
|
paul@56 | 316 | form.
|
paul@56 | 317 | * Added a parent page parameter which is used by the new event form to place
|
paul@56 | 318 | new event pages in a particular location specific to a calendar or
|
paul@56 | 319 | collection of events.
|
paul@56 | 320 | * Improved the presentation of pop-up event information elements.
|
paul@59 | 321 | * Added navigation between display modes (calendar, list and table views).
|
paul@59 | 322 | * Ensured that calendar settings are retained when creating new events for a
|
paul@59 | 323 | calendar.
|
paul@59 | 324 | * Fixed various problems with events not having topics.
|
paul@51 | 325 |
|
paul@45 | 326 | New in EventAggregator 0.3 (Changes since EventAggregator 0.2)
|
paul@45 | 327 | --------------------------------------------------------------
|
paul@45 | 328 |
|
paul@45 | 329 | * Added a parameter to the EventAggregatorSummary action to select the
|
paul@45 | 330 | source of event descriptions for the RSS feed.
|
paul@45 | 331 | * Updated the documentation to cover the RSS support.
|
paul@47 | 332 | * Added the EventAggregatorNewEvent action.
|
paul@45 | 333 |
|
paul@41 | 334 | New in EventAggregator 0.2 (Changes since EventAggregator 0.1)
|
paul@41 | 335 | --------------------------------------------------------------
|
paul@41 | 336 |
|
paul@41 | 337 | * Improved the calendar view in the macro to use the fixed table layout
|
paul@41 | 338 | algorithm and to provide cells spanning potentially many columns for
|
paul@41 | 339 | continuing events. Introduced pop-up elements in order to show truncated
|
paul@41 | 340 | event names.
|
paul@41 | 341 | * Made the "weekly" naming policy the default in the calendar view.
|
paul@41 | 342 | * Improved the list view in the macro.
|
paul@41 | 343 | * Introduced RSS 2.0 feed support.
|
paul@41 | 344 | * Improved the help pages.
|
paul@41 | 345 |
|
paul@6 | 346 | Release Procedures
|
paul@6 | 347 | ------------------
|
paul@6 | 348 |
|
paul@18 | 349 | Update the EventAggregatorSupport.py __version__ attribute and the setup.py
|
paul@18 | 350 | version details.
|
paul@6 | 351 | Change the version number and package filename/directory in the documentation.
|
paul@51 | 352 | Update the setup.py and PKG-INFO files.
|
paul@6 | 353 | Update the release notes (see above).
|
paul@6 | 354 | Tag, export.
|
paul@6 | 355 | Archive, upload.
|
paul@10 | 356 | Update the MacroMarket and ActionMarket (see above for the URLs).
|