EventAggregator

Annotated README.txt

77:1371711798d6
74:3c3880a95e38
73:155ceab3c122
2010-02-04 Paul Boddie file changeset files shortlog Fixed parent page trimming from event summaries where an empty parent page name is given. Introduced parent page support in the summary action in order to remove unwanted page components from events with non-overridden summaries.
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@65    155 
New in EventAggregator 0.5 (Changes since EventAggregator 0.4)

 
 paul@65    156 
--------------------------------------------------------------

 
 paul@65    157 
 
 paul@65    158 
  * Changed the EventAggregatorNewEvent action to substitute only the stated

 
 paul@65    159 
    title, not the full page title, into the new page.

 
 paul@66    160 
  * Changed event colouring to use the event summary as the basis for

 
 paul@66    161 
    calculating the colour used in the calendar. This means that related

 
 paul@66    162 
    events can be coloured identically if their summaries are the same.

 
 paul@71    163 
  * Added support for multiple events on a single event page.

 
 paul@71    164 
  * Introduced EventPage and Event abstractions in order to better support new

 
 paul@71    165 
    features.

 
 paul@73    166 
  * Introduced basic and advanced modes to the EventAggregatorNewEvent action.

 
 paul@65    167 
 
 paul@51    168 
New in EventAggregator 0.4 (Changes since EventAggregator 0.3)

 
 paul@51    169 
--------------------------------------------------------------

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

 
 paul@51    172 
    provide background colours for events.

 
 paul@56    173 
  * Added category propagation from calendars to the new event form provided

 
 paul@56    174 
    by the EventAggregatorNewEvent action.

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

 
 paul@56    176 
    form.

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

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

 
 paul@56    179 
    collection of events.

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

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

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

 
 paul@59    183 
    calendar.

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

 
 paul@51    185 
 
 paul@45    186 
New in EventAggregator 0.3 (Changes since EventAggregator 0.2)

 
 paul@45    187 
--------------------------------------------------------------

 
 paul@45    188 
 
 paul@45    189 
  * Added a parameter to the EventAggregatorSummary action to select the

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

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

 
 paul@47    192 
  * Added the EventAggregatorNewEvent action.

 
 paul@45    193 
 
 paul@41    194 
New in EventAggregator 0.2 (Changes since EventAggregator 0.1)

 
 paul@41    195 
--------------------------------------------------------------

 
 paul@41    196 
 
 paul@41    197 
  * Improved the calendar view in the macro to use the fixed table layout

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

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

 
 paul@41    200 
    event names.

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

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

 
 paul@41    203 
  * Introduced RSS 2.0 feed support.

 
 paul@41    204 
  * Improved the help pages. 

 
 paul@41    205 
 
 paul@6    206 
Release Procedures

 
 paul@6    207 
------------------

 
 paul@6    208 
 
 paul@18    209 
Update the EventAggregatorSupport.py __version__ attribute and the setup.py

 
 paul@18    210 
version details.

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

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

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

 
 paul@6    214 
Tag, export.

 
 paul@6    215 
Archive, upload.

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