1 ##master-page:HelpTemplate 2 ##master-date:Unknown-Date 3 #format wiki 4 #language en 5 6 == EventAggregator == 7 8 The !EventAggregator macro for !MoinMoin can be used to display event calendars or listings which obtain their data from pages belonging to specific categories (such as CategoryEvents). 9 10 == Creating Events == 11 12 The easiest way to create an event is to click on a day number in a calendar. If you do not have a calendar set up, take a look at the instructions for [[#PreparingACalendar|preparing]] and [[#ShowingEventCalendars|showing]] calendars first. 13 14 Each event must be created on a new page belonging to the appropriate event category. The following action can be used to create a new event page (using !EventAggregatorNewEvent) without looking at a calendar: 15 16 (!) <<Action(EventAggregatorNewEvent,Add an event)>> 17 18 Since each event is represented by a page, creating a new page based on an appropriate template is also sufficient. For pages belonging to CategoryEvents, you can do this by filling out and submitting this form (which uses EventTemplate): 19 20 <<NewPage(EventTemplate,Add an event page)>> 21 22 The event page describes the event in more detail, and the start and end dates of the event must be specified in a definition list so that they can be read from the page and displayed by the !EventAggregator. The EventTemplate provides some guidance, and all you need to do is to replace the `YYYY-MM-DD` placeholders with actual year, month and day values. For example: 23 24 {{{ 25 Start:: 2009-06-28 26 End:: 2009-07-04 27 }}} 28 29 You can add text which is more readable for humans provided that the `YYYY-MM-DD` format values are present somewhere in each entry. For example: 30 31 {{{ 32 Start:: Sunday 28th June 2009 (2009-06-28) 33 End:: Saturday 4th July 2009 (2009-07-04) 34 }}} 35 36 Obviously, duplicating the date information introduces a risk of this information becoming inconsistent, so beware! 37 38 === Supported Event Properties === 39 40 As well as the start and end dates of an event, the following properties are also recognised as being part of an event description: 41 42 Title:: the preferred name of the event in the calendar 43 Summary:: a synonym for title 44 Topics:: a list of topics related to the event - use a comma (`,`) to separate topic names 45 Categories:: a synonym for topics - note that this means "event categories", not "page categories" which are a distinct concept 46 Location:: the location of the event 47 48 These properties may be incorporated into representations or summaries of events. 49 50 Textual properties can be quoted in a limited way using the verbatim or monospaced text Wiki syntax. For example: 51 52 {{{ 53 Summary:: <<Verbatim(EuroPython)>> 2009 54 Topics:: Python, <<Verbatim(EuroPython)>>, Zope 55 }}} 56 57 <<Anchor(PreparingACalendar)>> 58 == Preparing a Calendar == 59 60 Before trying to show a calendar or trying to create any events, first decide on a category for your events. You can create a new category for this purpose by filling out and submitting this form: 61 62 <<NewPage(CategoryTemplate,Add a new category,,Category%s)>> 63 64 It is not strictly necessary to have a dedicated category for events, but having such categories can make event management easier by preventing event pages getting mixed up with other kinds of pages. And since pages can belong to more than one category, you can still assign event pages to other categories and yet isolate the event pages via their own category when you need to. 65 66 <<Anchor(ShowingEventCalendars)>> 67 == Showing Event Calendars == 68 69 To show a calendar, use the !EventAggregator macro with a list of event categories. For example: 70 71 {{{ 72 ## Show Events and Training categories. 73 <<EventAggregator(CategoryEvents,CategoryTraining)>> 74 }}} 75 76 The calendar, shown by default, is automatically filled out with the details of each event in the specified category (or categories), colouring each event period in an automatically generated colour. 77 78 Specific periods can be defined using the `start` and `end` parameters. For example: 79 80 {{{ 81 ## Show June and July 2009. 82 <<EventAggregator(CategoryEvents,start=2009-06,end=2009-07)>> 83 }}} 84 85 By using specific month values, a fixed window of time can be presented, displaying only events occurring within that period. It is possible to omit `start` or `end` in order to show all events up to (by omitting `start`) or starting from (by omitting `end`) a particular month. 86 87 There are special values which are significant. The `current` value refers to the current month and can be used with the minus and plus operators to refer, respectively, to months before and after the current month: 88 89 {{{ 90 ## Show this and next month. 91 <<EventAggregator(CategoryEvents,start=current,end=current+1)>> 92 ## Show this and last month. 93 <<EventAggregator(CategoryEvents,start=current-1,end=current)>> 94 }}} 95 96 In addition, the `yearstart` and `yearend` values refer to the first and last months of the current year: 97 98 {{{ 99 ## Show this year's events. 100 <<EventAggregator(CategoryEvents,start=yearstart,end=yearend)>> 101 ## Show events from last December to next January. 102 <<EventAggregator(CategoryEvents,start=yearstart-1,end=yearend+1)>> 103 }}} 104 105 === Event Naming === 106 107 The default calendar view shows event names once per week. However, you can choose to show an event name on each day an event occurs: 108 109 {{{ 110 ## Show the name on every day. 111 <<EventAggregator(CategoryEvents,names=daily)>> 112 ## Show the name once per week. 113 <<EventAggregator(CategoryEvents,names=weekly)>> 114 }}} 115 116 === Navigation Controls === 117 118 The above examples have all provided fixed views of known events. However, a set of controls can be added to a calendar in order to let users navigate different time periods. This is done by providing a `calendar` parameter, indicating the name of the calendar, and by specifying a period of time: 119 120 {{{ 121 ## Provide a navigable calendar. 122 <<EventAggregator(CategoryEvents,start=current,end=current,calendar=monthly)>> 123 }}} 124 125 Without any time period, the calendar would show all events, and there would be no real need to provide navigation, since there would be no events outside the displayed period to navigate to. It is possible to omit either the `start` or the `end` parameter and still provide navigation, however. 126 127 === Assigning Templates and Parent Pages === 128 129 New events can be added to a calendar by following the links on each of the day numbers; this opens the form provided by the !EventAggregatorNewEvent action. For all events belonging to a particular calendar, it can be convenient to assign a default template page, so that the information provided by such events is consistent. Thus, it is possible to specify such a template page using the `template` parameter. For example: 130 131 {{{ 132 ## Specify a particular template page as the default event page template. 133 <<EventAggregator(CategoryEvents,template=SpecialEventTemplate)>> 134 }}} 135 136 It can also be convenient to add new event pages under a common parent page. This can be achieved by specifying such a page using the `parent` parameter. For example: 137 138 {{{ 139 ## Specify a particular parent page as the default container for new events. 140 <<EventAggregator(CategoryEvents,parent=Events)>> 141 }}} 142 143 Creating an event called '''Meeting''' under a parent called '''Events''' will make the page '''Events/Meeting''', and this will be shown as '''Meeting''' in the calendar. However, if a different parent is chosen, such as '''Meetings''', then the full path to the page will be shown in the calendar: '''Meetings ? Meeting'''. 144 145 == Showing Event Lists and Tables == 146 147 A more plain view of events can be displayed by specifying the `mode` parameter as follows: 148 149 {{{ 150 <<EventAggregator(CategoryEvents,mode=list)>> 151 }}} 152 153 The `list` value causes a list view to be employed. 154 155 Another alternative view can be chosen by specifying the `mode` parameter with a value of `table` as in the following example: 156 157 {{{ 158 <<EventAggregator(CategoryEvents,mode=table)>> 159 }}} 160 161 This collects all appropriate events into a single table, applying colouring to the cells belonging to a particular event based on that event's topic (or category) information. By default, only the following topics (or categories) cause cell colouring: 162 163 * `conference` - using the `event-table-category-conference` style 164 * `special` - using the `event-table-category-special` style 165 * `training` - using the `event-table-category-training` style 166 167 To define your own topic colours, edit the `event-aggregator.css` file which is provided with the !EventAggregator distribution, and then reinstall that file for each of the Wiki themes of interest. Topics involved in event colouring should be mutually exclusive: more than one such topic should not be specified for any given event. 168 169 === The Default View and Switching Views === 170 171 The `calendar` value for the `mode` parameter causes the default calendar view to be employed, but you can switch the view - effectively changing the `mode` - using the links provided below the view produced by this macro. 172 173 == See Also == 174 175 * HelpOnEventAggregatorNewEvent - an action providing a form for creating new events conveniently 176 * HelpOnEventAggregatorSummary - an action producing iCalendar event summaries