EventAggregator

Annotated README.txt

18:83350447c606
13:3f157ff51c55
10:8d6569566242
2009-03-25 Paul Boddie file changeset files shortlog Made the daterange function only permit descending ranges through an explicitly specified step parameter. Added a simple span function which just subtracts the last date from the first, returning the year and month differences in a tuple. Added a function which defines a "concrete" time period based on window and event information. Removed the 'span' macro parameter and introduced "current" month notation to replace the restrictive "last" and "next" values for 'start' and 'end'. Improved navigation links, employing 'start' and 'end' parameters.
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).