EventAggregator

Annotated README.txt

56:4b0e0c5022a1
54:df75a72e54fe
51:c8ca5d3a4587
2009-10-30 Paul Boddie file changeset files shortlog Revert previously added link rule, since it probably doesn't do anything extra.
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@6     23 
Installation

 
 paul@6     24 
------------

 
 paul@6     25 
 
 paul@10     26 
To install the support library, consider using the setup.py script provided:

 
 paul@10     27 
 
 paul@10     28 
  python setup.py install

 
 paul@10     29 
 
 paul@10     30 
You may wish to indicate a specific prefix if MoinMoin is not installed in the

 
 paul@10     31 
traditional location:

 
 paul@10     32 
 
 paul@10     33 
  python setup.py install --prefix=path-to-moin-prefix

 
 paul@10     34 
 
 paul@6     35 
To install the macro in a Wiki, consider using the instmacros script provided:

 
 paul@6     36 
 
 paul@6     37 
  ./instmacros path-to-wiki

 
 paul@6     38 
 
 paul@6     39 
On non-UNIX platforms, it is necessary to manually copy the contents of the

 
 paul@6     40 
macros directory in this distribution into the macros directory of your Wiki.

 
 paul@6     41 
 
 paul@10     42 
It is highly recommended that the tables and listings be styled according to

 
 paul@10     43 
the stylesheet provided, and you can use this file as a starting point for

 
 paul@10     44 
your own modifications. To install the stylesheet, consider using the

 
 paul@10     45 
insttheme script provided:

 
 paul@10     46 
 
 paul@10     47 
  ./insttheme path-to-wiki theme-name

 
 paul@10     48 
 
 paul@10     49 
Again, on non-UNIX platforms, it is necessary to manually copy the files. In

 
 paul@10     50 
this case, just copy the contents of the css directory into the css directory

 
 paul@10     51 
of themes which will support styling of event calendars and listings.

 
 paul@10     52 
 
 paul@10     53 
To activate the styles provided by the stylesheet in the css directory, you

 
 paul@10     54 
will need to edit the screen.css file in each affected theme's css directory,

 
 paul@10     55 
adding the following before any style rules:

 
 paul@10     56 
 
 paul@10     57 
  /* Event aggregation... */

 
 paul@10     58 
 
 paul@10     59 
  @import "event-aggregator.css";

 
 paul@10     60 
 
 paul@10     61 
This ensures that the styles are made available to the browser.

 
 paul@10     62 
 
 paul@47     63 
To install the actions in a Wiki, consider using the instactions script provided:

 
 paul@10     64 
 
 paul@10     65 
  ./instactions path-to-wiki

 
 paul@10     66 
 
 paul@10     67 
On non-UNIX platforms, it is necessary to manually copy the contents of the

 
 paul@10     68 
actions directory in this distribution into the actions directory of your Wiki.

 
 paul@10     69 
 
 paul@27     70 
Useful Pages

 
 paul@27     71 
------------

 
 paul@27     72 
 
 paul@27     73 
The pages directory contains a selection of useful pages using a syntax

 
 paul@27     74 
appropriate for use with MoinMoin 1.6 or later. These pages can be created

 
 paul@27     75 
through the Wiki and their contents copied in from each of the files.

 
 paul@27     76 
 
 paul@10     77 
Using the Macro

 
 paul@10     78 
---------------

 
 paul@10     79 
 
 paul@6     80 
It should now be possible to edit pages and use the macro as follows. For

 
 paul@6     81 
MoinMoin 1.5:

 
 paul@6     82 
 
 paul@20     83 
  [[EventAggregator(CategoryEvents)]]

 
 paul@6     84 
 
 paul@6     85 
For MoinMoin 1.6 and above:

 
 paul@6     86 
 
 paul@20     87 
  <<EventAggregator(CategoryEvents)>>

 
 paul@6     88 
 
 paul@6     89 
As arguments to the macro, you must indicate a comma-separated list of

 
 paul@6     90 
categories to be inspected for event data. For example:

 
 paul@6     91 
 
 paul@20     92 
  <<EventAggregator(CategoryEvents,CategoryTraining)>>

 
 paul@6     93 
 
 paul@6     94 
By default, this should display a calendar in a collection of tables, one for

 
 paul@6     95 
each month containing events. To show a collection of month-by-month listings,

 
 paul@6     96 
use the 'mode' argument as follows:

 
 paul@6     97 
 
 paul@20     98 
  <<EventAggregator(CategoryEvents,mode=list)>>

 
 paul@20     99 
 
 paul@20    100 
See pages/HelpOnEventAggregator for more detailed information.

 
 paul@6    101 
 
 paul@47    102 
Using the Actions

 
 paul@47    103 
-----------------

 
 paul@6    104 
 
 paul@20    105 
To obtain an iCalendar summary, the EventAggregatorSummary action can be

 
 paul@20    106 
selected from the actions menu on any page. Alternatively, a collection of

 
 paul@24    107 
parameters can be specified in the URL of any Wiki page.

 
 paul@6    108 
 
 paul@24    109 
See pages/HelpOnEventAggregatorSummary for more detailed information.

 
 paul@6    110 
 
 paul@47    111 
To create new events using the EventAggregatorNewEvent action, the appropriate

 
 paul@47    112 
menu entry can be selected in the actions menu. Alternatively, clicking on a

 
 paul@47    113 
day number in a calendar view will invoke the action and pre-fill the form

 
 paul@47    114 
with the start date set to the selected day from the calendar.

 
 paul@47    115 
 
 paul@47    116 
See pages/HelpOnEventAggregatorNewEvent for more detailed information.

 
 paul@47    117 
 
 paul@6    118 
Recommended Software

 
 paul@6    119 
--------------------

 
 paul@6    120 
 
 paul@6    121 
The Xapian search software is highly recommended, if not technically

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

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

 
 paul@6    124 
spent processing requests.

 
 paul@6    125 
 
 paul@6    126 
See the following page for information on Xapian and MoinMoin:

 
 paul@6    127 
 
 paul@6    128 
http://moinmo.in/HelpOnXapian

 
 paul@6    129 
 
 paul@6    130 
Troubleshooting

 
 paul@6    131 
---------------

 
 paul@6    132 
 
 paul@6    133 
See here for a bug related to category recognition:

 
 paul@6    134 
 
 paul@6    135 
http://moinmo.in/MoinMoinBugs/1.7TemplatesNotAppearing

 
 paul@6    136 
 
 paul@6    137 
This affects installations where migrations between versions have occurred,

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

 
 paul@6    139 
 
 paul@6    140 
Contact, Copyright and Licence Information

 
 paul@6    141 
------------------------------------------

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

 
 paul@6    144 
 
 paul@6    145 
http://moinmo.in/MacroMarket/EventAggregator

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

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

 
 paul@6    149 
 
 paul@6    150 
paul@boddie.org.uk

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

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

 
 paul@6    154 
 
 paul@51    155 
New in EventAggregator 0.4 (Changes since EventAggregator 0.3)

 
 paul@51    156 
--------------------------------------------------------------

 
 paul@51    157 
 
 paul@51    158 
  * Added a table view in the macro, using special topic/category styles to

 
 paul@51    159 
    provide background colours for events.

 
 paul@51    160 
 
 paul@45    161 
New in EventAggregator 0.3 (Changes since EventAggregator 0.2)

 
 paul@45    162 
--------------------------------------------------------------

 
 paul@45    163 
 
 paul@45    164 
  * Added a parameter to the EventAggregatorSummary action to select the

 
 paul@45    165 
    source of event descriptions for the RSS feed.

 
 paul@45    166 
  * Updated the documentation to cover the RSS support.

 
 paul@47    167 
  * Added the EventAggregatorNewEvent action.

 
 paul@45    168 
 
 paul@41    169 
New in EventAggregator 0.2 (Changes since EventAggregator 0.1)

 
 paul@41    170 
--------------------------------------------------------------

 
 paul@41    171 
 
 paul@41    172 
  * Improved the calendar view in the macro to use the fixed table layout

 
 paul@41    173 
    algorithm and to provide cells spanning potentially many columns for

 
 paul@41    174 
    continuing events. Introduced pop-up elements in order to show truncated

 
 paul@41    175 
    event names.

 
 paul@41    176 
  * Made the "weekly" naming policy the default in the calendar view.

 
 paul@41    177 
  * Improved the list view in the macro.

 
 paul@41    178 
  * Introduced RSS 2.0 feed support.

 
 paul@41    179 
  * Improved the help pages. 

 
 paul@41    180 
 
 paul@6    181 
Release Procedures

 
 paul@6    182 
------------------

 
 paul@6    183 
 
 paul@18    184 
Update the EventAggregatorSupport.py __version__ attribute and the setup.py

 
 paul@18    185 
version details.

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

 
 paul@51    187 
Update the setup.py and PKG-INFO files.

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

 
 paul@6    189 
Tag, export.

 
 paul@6    190 
Archive, upload.

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