EventAggregator

Annotated README.txt

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