notificationsEmailPreferences
Audit
- Macro ID
- notificationsEmailPreferences
- Source
- XS
- Type
- Generator
- Classification reason
- The macro has no content: its whole output is a form of two lists built from the preferences of a user or of the wiki, given by its parameters and the context, like notifications and mention.
- Status
- Reviewed
- Criteria version
- 15.20
- XWiki version
- 18.8.0
- Audit date
- 2026-10-20
- Auditor
- Compared macros
- notifications mention
Lucas CharpentierSources
Where to gather the information the criteria are checked against, see Gather the sources.
| Other sources specific to this macro |
|---|
|
| Criterion | Result | Notes |
|---|---|---|
| D1 wording | OK | "Notifications Email Preferences" is the user's wording for the settings of the emails sent for notifications, the same words as the Email preferences heading of the notifications administration and of the profile. The name is long: 31 characters, one more than Quick Actions reads, see D4. |
| D2 summary | KO | "Display the preferences of the current user about notification emails." repeats the name and is wrong for two of the uses of the macro: with target="wiki" it displays the default email preferences of the whole wiki, and with user="XWiki.Admin" the preferences of another user, which an administrator can edit. It does not say that the result is a form with two lists, the email frequency and the level of detail of the changes, where a change is saved right away. |
| D3 category | KO | Notifications, but the macro is only meant for the notification administration and preferences UI, where it has its own entry, not to be inserted in a page, so it should be in the Internal category. Only the Internal and Deprecated categories are hidden from the Quick Actions menu and the Insert Macro dialog, for the users who do not display hidden pages; Notifications keeps it listed for every user. See XWIKI-21063. |
| D4 quick-action | KO | the synonyms are "email notifications", "email frequency", "email digest", "notification settings" and "notification preferences". Quick Actions finds the macro first for its ID "notificationsEmailPreferences" and for "email preferences", "notification emails", "mail preferences", "email" and "emails". The five synonyms above give no result, "notification settings" and "notification preferences" included. Typing the full name "Notifications Email Preferences" gives no result, since it has 31 characters and Quick Actions reads 30 after the slash, a generic limit of the xwiki-slash plugin; "Notifications Email Pref" finds it. The French and German names are the English one, so no other language is checked. "notifications email" lists the macro first, then "Notifications Filters Preferences (deprecated)", "Notifications Applications Preferences" and "Notifications Auto Watch Preferences". Whether each synonym is worth supporting is decided when filing the ticket. |
| L1 consistency | OK | compared with notifications and mention: like notifications, no parameter is mandatory, there is no content and the Quick Action inserts the macro right away, with no dialog, unlike mention, whose reference is mandatory, which is by design. Like notifications, it declares the default of its parameters. |
| L2 doc-parameters | KO | minor: the only documentation is the page Notification Settings Macros of the administration documentation: one table row per settings macro, and one paragraph shared by the five of them, saying that target is user or wiki and that user defaults to the current user. It has no parameter table, no default for target and no mandatory flags. |
| L3 doc-example | KO | the Notification Settings Macros page has no example of the most common call, the call of the user profile in XWiki Standard: it only gives the bare {{notificationsEmailPreferences/}} in its table, and its screenshot shows the email preferences macro. The example used for the other criteria is {{notificationsEmailPreferences user="XWiki.Admin" /}} . |
| I1 pattern | OK | compared with children, the reference generator: from the Quick Actions menu, entry "Notifications Email Preferences" found with "email preferences", the macro is inserted without a dialog and selected, with an empty paragraph after it. From the Insert Macro dialog the Edit Macro dialog opens, whose fields are both optional, like children. |
| I2 zero-config | OK | inserting from Quick Actions or from the Insert Macro dialog with the default values gives {{notificationsEmailPreferences/}} , which shows the two lists for the preferences of the current user, in the editor and in view mode, with no error. A guest sees an information message instead, and a wiki where the emails are disabled a warning. |
| I3 instant | N/A | |
| I4 cursor | N/A | |
| I5 focus | OK | no parameter is mandatory. The focus is on the first field, Target, a field that few users have to change, while the field they may want, User, is second, see C6. |
| E1 wysiwyg | OK | the editor shows the same two lists as view mode, the Email Frequency and the Details of the changes, with only the macro frame and its name above. |
| E2 errors | KO | invalid values are accepted silently. {{notificationsEmailPreferences target="maybe"/}} , target="" and the wrong case target="WIKI" show the same form as the valid values with no message, as the preferences of the wiki, but the lists then fail to save: the macro sends the target to the notification preference service, which only accepts "user" and "wiki" and answers 401, and the page shows "Failed to save your settings" at the first change. {{notificationsEmailPreferences user="xwiki:XWiki.NoSuchUser"/}} , user="abc" , which is read as XWiki.abc, and user="Main.WebHome" show the form of a user that does not exist with no message, and a change fails the same way, with a 400. user="" shows "The given user reference is not supported, only DocumentUserReference are supported for now.", which does not name the parameter. A user without the administration right on the given user sees "You dont have administration right for the given user: {0}.", with the placeholder {0} not replaced by the reference, so the message does not say which user. |
| E3 nesting | KO | in a list item and in a table cell, * {{notificationsEmailPreferences/}} , the macro shows "The [notificationsEmailPreferences] macro is a standalone macro and it cannot be used inline." in the editor and in view mode. In a box it renders. The macro has no content, so the second half of the measure does not apply. |
| E4 inline-support | OK | the macro declares no inline support, and its output is a form with two labelled lists, blocks that cannot be inside a sentence. |
| E5 empty | N/A | E6: the macro has no content. |
| E6 inplace | N/A |
Parameters
| Parameter | C1 clarity | C2 mandatory | C3 defaults | C4 input-assistance | C5 groups | C6 order | C7 alternatives | C8 advanced | C9 technical | C13 constraints | Notes |
|---|---|---|---|---|---|---|---|---|---|---|---|
| target | KO | OK | OK | KO | OK | OK | N/A | KO | OK | N/A | C1: the field has no description, so the dialog does not say what a target is nor which values it accepts. The valid values, "user" and "wiki", appear nowhere in the dialog, and "wiki" needs the administration right. C3: the field opens on the declared default, "user", which is the use of the example. C4: a plain text field for a choice between two values, user and wiki, which a select would fit, see E2: any other value is accepted silently. C8, minor: "wiki" shows the default preferences of the whole wiki and is only meant for the notifications administration section, which XWiki Standard sets once, while the example of the profile of a user sets only user. The field is not marked as advanced. C13: the accepted values are a fixed list, counted under C4. |
| user | KO | OK | OK | OK | OK | OK | N/A | OK | OK | OK | C1: the description is "User reference of the user for which to display and manipulate the email preferences. This parameter is optional, only used if the target parameter is set to user and default value is the context user. Note that for using this parameter, the context user needs administrator right on the given user reference." The dialog shows the wiki markup user as is. It refers to another field by its parameter ID, "the target parameter", instead of its label, and uses developer terms, "user reference" and "context user", instead of saying that the field empty means the user who views the page, and the sentence about the administration right is hard to follow. C3: the picker opens empty, which means the user who views the page, as the description says, and the value of the example, the user of the profile, differs on each page, so no value can be preselected. C4: a user picker, which suggests the users matching what the user types: "Adm" lists "Administrator". |
Other notes
Outside the criteria: the message of the user without the administration right on the given user shows the unreplaced {0}, see E2.
KOs and tickets
Every KO needs a ticket covering it, see Report the KOs. One ticket can cover several KOs. Known issues filed for this macro are suggested in italics: link them as existing tickets when they cover the KO.
| KO | Criterion | Existing tickets | New tickets |
|---|---|---|---|
| D2 | D2 summary | XWIKI-25468 | |
| D3 | D3 category | XWIKI-21063 | XWIKI-25468 |
| D4 | D4 quick-action | XWIKI-25468 | |
| L2 | L2 doc-parameters | XWIKI-25468, XINFRA-525 | |
| L3 | L3 doc-example | XWIKI-25468, XINFRA-526 | |
| E2 | E2 errors | XCOMMONS-3847 (partial), XRENDERING-823 (partial), XWIKI-25468 | |
| E3 | E3 nesting | XWIKI-25468 | |
| C1:target | C1 clarity, target | XWIKI-25468 | |
| C4:target | C4 input-assistance, target | XWIKI-25468 | |
| C8:target | C8 advanced, target | XWIKI-25468 | |
| C1:user | C1 clarity, user | XWIKI-25468 |
Tickets
| Ticket | Origin | KOs covered | KOs partly covered |
|---|---|---|---|
| XWIKI-21063 | Existing | D3 | |
| XCOMMONS-3847 | New | E2 | |
| XRENDERING-823 | New | E2 | |
| XWIKI-25468 | New | C1:target C1:user C4:target C8:target D2 D3 D4 E2 E3 L2 L3 | |
| XINFRA-525 | New | L2 | |
| XINFRA-526 | New | L3 |
Known issues of this macro
No known issue is specific to this macro.
68 more known issues affect every macro: see the Known issues.
