EventAggregator

Annotated README.txt

65:09b6994cda31
61:821221660448
59:7f2571ba55e3
2009-11-08 Paul Boddie file changeset files shortlog Fixed the table view by just showing all events in the chosen period, not traversing each month and showing that month's events, which leads to events being duplicated if they span month boundaries.
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@56    160 
  * Added category propagation from calendars to the new event form provided

 
 paul@56    161 
    by the EventAggregatorNewEvent action.

 
 paul@56    162 
  * Added a default template parameter to the macro, employed by the new event

 
 paul@56    163 
    form.

 
 paul@56    164 
  * Added a parent page parameter which is used by the new event form to place

 
 paul@56    165 
    new event pages in a particular location specific to a calendar or

 
 paul@56    166 
    collection of events.

 
 paul@56    167 
  * Improved the presentation of pop-up event information elements.

 
 paul@59    168 
  * Added navigation between display modes (calendar, list and table views).

 
 paul@59    169 
  * Ensured that calendar settings are retained when creating new events for a

 
 paul@59    170 
    calendar.

 
 paul@59    171 
  * Fixed various problems with events not having topics.

 
 paul@51    172 
 
 paul@45    173 
New in EventAggregator 0.3 (Changes since EventAggregator 0.2)

 
 paul@45    174 
--------------------------------------------------------------

 
 paul@45    175 
 
 paul@45    176 
  * Added a parameter to the EventAggregatorSummary action to select the

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

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

 
 paul@47    179 
  * Added the EventAggregatorNewEvent action.

 
 paul@45    180 
 
 paul@41    181 
New in EventAggregator 0.2 (Changes since EventAggregator 0.1)

 
 paul@41    182 
--------------------------------------------------------------

 
 paul@41    183 
 
 paul@41    184 
  * Improved the calendar view in the macro to use the fixed table layout

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

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

 
 paul@41    187 
    event names.

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

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

 
 paul@41    190 
  * Introduced RSS 2.0 feed support.

 
 paul@41    191 
  * Improved the help pages. 

 
 paul@41    192 
 
 paul@6    193 
Release Procedures

 
 paul@6    194 
------------------

 
 paul@6    195 
 
 paul@18    196 
Update the EventAggregatorSupport.py __version__ attribute and the setup.py

 
 paul@18    197 
version details.

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

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

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

 
 paul@6    201 
Tag, export.

 
 paul@6    202 
Archive, upload.

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