From version 109.1
edited by Clemens Robbenhaar
on 2019/07/27 23:58
To version 110.1
edited by Clemens Robbenhaar
on 2019/07/28 00:09
Change comment: add preliminary notes for the soon-to-be-released recurrent events feature



... ... @@ -56,6 +56,41 @@
56 56  {{image reference="EditCalendar.png"/}}
57 57  //Editing a calendar//
58 58  
59 +=== Recurrent Events ===
60 +
61 +{{error}}
62 +Recurrent events are **not yet implemented**. They will be available in version 2.7, which will be released soon.
63 +{{/error}}
64 +
65 +When you create a new event, you will see a checkbox at the bottom of the form. If you check that box, new fields will become visible to define the recurrence information of the event:
66 +
67 +{{image reference="create-recurrent-event.png"/}}
68 +//Create a recurrent event//
69 +
70 +At the moment you can choose between daily, on workdays (except Sunday), weekly, biweekly, monthly, quarterly and yearly events.
71 +You can leave the "first occurrence" field empty; it will by default set to the start date of the event.
72 +If you leave the "last occurrence" field empty, the event will repeat indefinitely. To avoid an infinite loop for "upcoming events" in the "agenda" view of the calendar, only the first 100 repetitions are shown in that view.
73 +
74 +{{image reference="edit-recurrent-event.png"/}}
75 +//Modify one instance of a recurrent event//
76 +
77 +If you edit one instance of a recurrent event, it will initially show you the entries for the current instance and lets you modify them. If you want to edit the settings for all instances, you can click on the "all instances" radio button at the top of the dialog.
78 +
79 +{{image reference="delete-recurrent-event.png"/}}
80 +//Dialog to delete a recurrent event//
81 +
82 +If you delete one instance of a recurrent event, you will be asked if you want to delete all instances of the event (with a red alert button), or just the current instance (click the "yes" button or press "enter").
83 +
84 +==== Limitations ====
85 +
86 +The current implementation has several limitations:
87 +
88 +* recurrent events cannot be moved via drag & drop on the calendar.
89 +* if an instance of an event is deleted, it cannot be restored via the UI. Go to the page view of the event and either roll back to the previous version via the page history, if the deletion was the last edit for that event, or open the page in the object editor and try to find out the ##MoccaCalendar.Code.MoccaCalendarEventDeletionClass## object with the right date and delete this object.
90 +* if the start date for all events is edited, any local modifications or deletions to event instances are not moved with the new event date, and will thus disappear.
91 +* while it has always been the case that date pickers do not open at the place of the input form if one scrolls while editing an event, this issue will now show up more often with the somewhat longer edit dialogs.
92 +
93 +
59 59  == iCalendar export ==
60 60  
61 61  You can use [[Mocca Calendar iCal export>>Extension.Mocca Calendar iCal export]] to add iCalendar export.
... ... @@ -64,6 +64,44 @@
64 64  
65 65  If you find a bug or have a suggestion for improvement, please report it in the [[Issue Tracker>>]]. Please check if the issue has been reported there already.
66 66  
102 +== Migration to 2.7 (recurrent events) ==
103 +
104 +When upgrading from a version before 2.7 to a version of 2.7 and higher, the upgrade step in the extension manager might take a bit longer; also some pages have been moved, and you will be asked to delete several unused pages after the upgrade. Please really do delete these pages, or you might end up with two variants of the same UI code from both versions, which will break the UI.
105 +
106 +If you have modified some pages like the ##Macro##, ##JSONService## or ##MoccaCalendarEventSheet##, you will likely run into some conflicts when upgrading. Better save your modifications before you upgrade and overwrite with the new version, then reapply your modifications manually. Please note that most pages (including the first two examples) has been moved to a subspace ##MoccaCalendar##.
107 +
108 +Some issues that might happen after the upgrade:
109 +
110 +=== Macro "moccacalendar" not found ===
111 +
112 +Because the old page defining this macro is deleted only after the new version is installed, this might cause confusion as for a short time two macros with the same name are around. After removing the old version of the macro, the new version might not be active.
113 +
114 +There are two workarounds to get rid of this error message:
115 +
116 +* restart the servlet container in which XWiki is running. This will find the new version of the macro while starting up.
117 +* go to the page https:~/~/<server>/xwiki/bin/view/MoccaCalendar/Code/Macro and make a dummy edit to that page, like inserting a few spaces somewhere. This will make XWiki aware of the new macro definition, even if you roll back that dummy edit instantly via the history. You need to repeat this step for every subwiki where the MoccaCalendar is installed.
118 +
119 +=== Some events are no longer shown in the calendars ===
120 +
121 +This might happen if the migration of the events did not run to completion. (The migration needs to add a new property to all existing events so they are recognized as "non-recurrent".)
122 +
123 +You can check if this is the case for some events by visiting the migration helper page at https:~/~/<server>/xwiki/bin/view/MoccaCalendar/Code/RecurrentEventMigration~.
124 +
125 +To re-run the migration you have two options:
126 +
127 +* restart the servlet container while adding a setting like to the command line. (It does not matter if you use "on" or any other text as value of the system property.) Check the server logs if they contain error messages from the migration, or end with "INFO: migrated all events on wiki ~[~<wikiname>]" - which of course only appears if the log level is set to INFO. Add a line like
128 +(((
129 +{{code}}
130 + <logger name="org.xwiki.contrib.moccacalendar" level="info"/>
131 +{{/code}}
132 +)))
133 +to the ##logback.xml## file to make sure you see these messages.
134 +* the migration helper page also contains a button to start the migration. You can select the batch size for the migration and start the migration manually for the current wiki. The page might sometimes stop the migration even though there are still events to migrate, for reasons currently not investigated. In that case reload the page and try again, maybe even several times. For error messages keeping the migration from running you still need to read the server logs on the file system, however.
135 +
136 +If none of these options help, please downgrade to the previous version and send a [[bug report>>||anchor="HIssues"]].
137 +
138 +If the migration helper page does not show any non-migrated events, then maybe some events have not been properly migrated to the "nested pages" structure. Please see the next section for remedies.
139 +
67 67  == Migration to Nested Pages (for 2.6 and higher) ==
68 68  
69 69  If you update this extension from a pre-2.6 version, you likely want to migrate all the calendars to become nested pages. For this you will need to run the [[Nested Pages Migrator>>doc:Extension.Nested Pages Migrator Application]] again (or maybe for the first time, if you set up the wiki with a version of 7.2 or later).

Get Connected