notifications

• Notifications macro translations, xwiki-platform: the name, description and parameter texts shown in the Edit Macro dialog.
• DefaultNotificationParametersFactory, xwiki-platform: how the parameters are read, which ones useUserPreferences replaces, and the formats of wikis, spaces, pages and tags.
• Help.Macros.Notifications on xwiki.org: two more examples, the wiki activity and the activity of the current user, written with Velocity for the current wiki and user.
• Legacy Notifications Macro page: no usage section and no parameter table, replaced by the new documentation.

C3: the field opens on the declared default, 10, while the most common example sets 5: the example only picks a smaller list, and 10 is the value of the usage line of the documentation, {{notifications /}} .

C4: a plain text field for a number of events, which a number field would fit.

C5: the 14 fields are all in the single group "Optional parameters", above 9, mixing the parameters that choose the events, useUserPreferences, wikis, spaces, pages, users, displayWatchedUsersOnly and tags, with the display options, count, displayRSSLink, displayReadStatus and the four display event checkboxes. The same holds for every parameter, see XWIKI-23835.

C13: the macro is a wiki macro, whose parameters cannot declare a range or a format, see XWIKI-25197 in the Cross-macro findings. count="-3" is accepted and shows one event.

C1: "If true, the preferences of the user about notifications are used" does not say that the user is the reader, nor that the macro then shows the reader's own notifications, but the field name and the descriptions of the filters, which say they are then ignored, make it clear enough.

C6: the switch between the two uses of the macro, the reader's own notifications or the activity of a part of the wiki, set by the third example of the documentation, is the 12th of the 14 fields and is only visible after scrolling. No order is declared, so the dialog sorts the fields by parameter ID.

C7: useUserPreferences and the filters wikis, spaces, pages, users, displayWatchedUsersOnly and tags are two alternative ways to choose the events, the reader's notification settings or explicit filters, which useUserPreferences makes ignored, but the dialog shows them as separate fields, with nothing telling that checking "Use the preferences of the user" makes the others ignored.

C8: rarely used, since the events XWiki triggers itself, like extension updates, are of little use in a list of changes, and not marked as advanced.

C8: rarely used, since the read marks are personal and mostly matter for the reader's own notifications, and not marked as advanced.

C1, minor: "Either or not the status of the events (either it has been marked as read or not) should be displayed" is garbled, and does not say that the status is also the control to mark an event as read.

C8: rarely used, a display detail, and not marked as advanced.

C1, minor: "List of wikis (comma-separated) to consider. This parameter is ignored if useUserPreferences is set to "true"." refers to another field by its parameter ID and value, "useUserPreferences is set to "true"", instead of its label, "Use the preferences of the user", and "to consider" does not say that only the events of these wikis are displayed. It does not say whether a wiki is given by its name or its ID.

C4: a plain text field for a list of wikis, which a wiki picker could offer, see XWIKI-23834.

C7: an alternative of useUserPreferences, which makes it ignored, shown as a separate field, see useUserPreferences.

C1, minor: "List of spaces (comma-separated) to consider." uses "space", a technical term that the UI no longer shows since nested pages. It refers to another field by its parameter ID and value, "useUserPreferences is set to "true"", instead of its label, "Use the preferences of the user", and "to consider" does not say that only the events of these locations are displayed, which includes their child pages.

C4: a plain text field for a list of locations, which a page picker could offer, see XWIKI-23834.

C7: an alternative of useUserPreferences, which makes it ignored, shown as a separate field, see useUserPreferences.

C1, minor: "List of pages (full references, comma-separated) to consider." gives no example of a full reference, like Sandbox.WebHome. It refers to another field by its parameter ID and value, "useUserPreferences is set to "true"", instead of its label, "Use the preferences of the user", and "to consider" does not say that only the events of these pages are displayed.

C4: a plain text field for a list of pages, which a page picker could offer, see XWIKI-23834.

C7: an alternative of useUserPreferences, which makes it ignored, shown as a separate field, see useUserPreferences.

C1, minor: "List of users to consider (comma-separated). Ignored if "useUserPreferences" is set to "true"." does not give the format of a user, like XWiki.Admin. It refers to another field by its parameter ID and value, "useUserPreferences is set to "true"", instead of its label, "Use the preferences of the user", and "to consider" does not say that only the events of these users are displayed.

C4: a plain text field for a list of users, which a user picker could offer, see XWIKI-23834.

C7: an alternative of useUserPreferences, which makes it ignored, shown as a separate field, see useUserPreferences. users and displayWatchedUsersOnly are also two alternatives for the same feature, whose events are displayed: when "Display followed users only" is checked, the macro replaces the users of this field with the people the reader follows, see displayWatchedUsersOnly.

C1: the description is wrong: "Display only the events performed by the given list of users (if empty, the list of followed users of the current user is used)" says that the users of the Users field are used when it is filled, while the macro always replaces them with the people the reader follows, and shows the warning "You are not following anybody." instead of any event when the reader follows nobody. To reproduce: {{notifications displayWatchedUsersOnly="true" users="XWiki.Admin"/}} for a reader who follows nobody shows only that warning.

C7: an alternative of useUserPreferences, which makes it ignored, shown as a separate field, see useUserPreferences. It is also an alternative of users, which it replaces, see users.

C1, minor: "List of tags to consider (comma-separated). It only works on the current wiki. Ignored if "useUserPreferences" is set to "true"." refers to another field by its parameter ID and value, "useUserPreferences is set to "true"", instead of its label, "Use the preferences of the user", and "to consider" does not say that only the events of pages carrying these tags are displayed.

C4: a plain text field for a list of tags, which a tag picker, like the one of the page tags, could offer, see XWIKI-23834.

C7: an alternative of useUserPreferences, which makes it ignored, shown as a separate field, see useUserPreferences.