EventAggregator

Annotated README.txt

18:83350447c606
16:f88e0568aaf8
10:8d6569566242
2009-03-26 Paul Boddie file changeset files shortlog Introduced more convincing calendar marking with "weekly" names on events.
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@6      6 
categories (such as CategoryEvent). 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@6     69 
  [[EventAggregator(CategoryEvent)]]

 
 paul@6     70 
 
 paul@6     71 
For MoinMoin 1.6 and above:

 
 paul@6     72 
 
 paul@6     73 
  <<EventAggregator(CategoryEvent)>>

 
 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@6     78 
  <<EventAggregator(CategoryEvent,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@6     84 
  <<EventAggregator(CategoryEvent,mode=list)>>

 
 paul@6     85 
 
 paul@10     86 
Using the Action

 
 paul@10     87 
----------------

 
 paul@6     88 
 
 paul@10     89 
To obtain an iCalendar summary, a collection of parameters can be specified in

 
 paul@10     90 
the URL of any Wiki page. For example:

 
 paul@10     91 
 
 paul@10     92 
  http://example.com/moin/FrontPage?action=EventAggregatorSummary&category=CategoryEvents

 
 paul@6     93 
 
 paul@10     94 
This should produce an iCalendar resource in response. By specifying 'start'

 
 paul@10     95 
and 'end' parameters, a restricted view can be obtained. For example:

 
 paul@6     96 
 
 paul@10     97 
  http://example.com/moin/FrontPage?action=EventAggregatorSummary&category=CategoryEvents&start=2009-06&end=2009-07

 
 paul@6     98 
 
 paul@10     99 
This would restrict the initial query to events occurring in the months of

 
 paul@10    100 
June 2009 ('2009-06') and July 2009 ('2009-07').

 
 paul@6    101 
 
 paul@6    102 
Recommended Software

 
 paul@6    103 
--------------------

 
 paul@6    104 
 
 paul@6    105 
The Xapian search software is highly recommended, if not technically

 
 paul@6    106 
essential, for the acceptable performance of the EventAggregator macro since

 
 paul@6    107 
the macro makes use of search routines in MoinMoin that can dominate the time

 
 paul@6    108 
spent processing requests.

 
 paul@6    109 
 
 paul@6    110 
See the following page for information on Xapian and MoinMoin:

 
 paul@6    111 
 
 paul@6    112 
http://moinmo.in/HelpOnXapian

 
 paul@6    113 
 
 paul@6    114 
Troubleshooting

 
 paul@6    115 
---------------

 
 paul@6    116 
 
 paul@6    117 
See here for a bug related to category recognition:

 
 paul@6    118 
 
 paul@6    119 
http://moinmo.in/MoinMoinBugs/1.7TemplatesNotAppearing

 
 paul@6    120 
 
 paul@6    121 
This affects installations where migrations between versions have occurred,

 
 paul@6    122 
yet the Wiki configuration retains old regular expression details.

 
 paul@6    123 
 
 paul@6    124 
Contact, Copyright and Licence Information

 
 paul@6    125 
------------------------------------------

 
 paul@6    126 
 
 paul@10    127 
See the following Web pages for more information about this work:

 
 paul@6    128 
 
 paul@6    129 
http://moinmo.in/MacroMarket/EventAggregator

 
 paul@10    130 
http://moinmo.in/ActionMarket/EventAggregator

 
 paul@6    131 
 
 paul@6    132 
The author can be contacted at the following e-mail address:

 
 paul@6    133 
 
 paul@6    134 
paul@boddie.org.uk

 
 paul@6    135 
 
 paul@6    136 
Copyright and licence information can be found in the docs directory - see

 
 paul@6    137 
docs/COPYING.txt and docs/LICENCE.txt for more information.

 
 paul@6    138 
 
 paul@6    139 
Release Procedures

 
 paul@6    140 
------------------

 
 paul@6    141 
 
 paul@10    142 
Update the EventAggregatorSupport.py __version__ attribute.

 
 paul@6    143 
Change the version number and package filename/directory in the documentation.

 
 paul@6    144 
Update the release notes (see above).

 
 paul@6    145 
Tag, export.

 
 paul@6    146 
Archive, upload.

 
 paul@10    147 
Update the MacroMarket and ActionMarket (see above for the URLs).