notificationsCustomFiltersPreferences
Audit
- Macro ID
- notificationsCustomFiltersPreferences
- Source
- XS
- Type
- Generator
- Classification reason
- The macro has no content: its whole output is a table of the custom notification filters of a user or of the wiki, with a button that adds one, built from 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.
| Source | What it gives | Used for | Where |
|---|---|---|---|
| Documentation | Parameters, default values and examples, including the most common example | L2, L3, and the criteria measured with the most common example | https://www.xwiki.org/xwiki/bin/view/documentation/xs/admin/notifications/settings-macros/ |
| Source code | How the macro declares its parameters and content: types, groups, features, advanced and hidden flags, constraints, content type, inline support | C4, C5, C7, C8, C9, C13, E4, E6 | Not recorded yet: search GitHub |
| Macro descriptor | What the Edit Macro dialog is built from, on design.xwiki.org | D1, D2, C1 to C9, E4 | Descriptor, list of macros with their categories |
| Translations | The name, description and parameter names in each language | D1, D2, D4, C1 | l10n.xwiki.org |
| Uses in XWiki pages | How XWiki itself uses the macro, a realistic example when the documentation has none | L3, C2, C3, C6, C8, C9 | Search the xwiki organization on GitHub |
| Compared macros | The audits of the macros of the same type | L1, D3 | notifications, mention |
| Other sources specific to this macro |
|---|
|
| Criterion | Result | Notes |
|---|---|---|
| D1 wording | OK | "Notifications Custom Filters Preferences" is the wording of the notification filters of the user profile and of the administration, "custom" being the filters that the user creates, as opposed to the system filters. The name is long, 40 characters, see D4. |
| D2 summary | KO | "Display the preferences of the given user about custom notification filters." repeats the name and is wrong for two of the uses of the macro: with target="wiki" it displays the custom filters of the whole wiki, and without user it displays those of the user who views the page, not "the given user". It does not say that the result is a table where the user adds, enables, disables and deletes filters, nor what a custom filter is. |
| 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 "notification filters", "filter preferences", "custom notification filters" and "watch filters". Quick Actions finds the macro first for "custom filters" and "custom filter", for the first 30 characters of its ID "notificationsCustomFiltersPref" and of "notificationsCustomFilters", and for the first 25 characters of its name, "Notifications Custom Filt", where it is the first result. The four synonyms above give no result for this macro: "notification filters" and "custom notification filters" only list "Notifications Filters Preferences (deprecated)", and "filter preferences" and "watch filters" list nothing. "filters" lists the deprecated macro first, then this one and the system filters one. The full name, 40 characters, and the full ID, 37 characters, give no result, since Quick Actions reads 30 characters after the slash, a generic limit of the xwiki-slash plugin. The French and German names are the English one, so no other language is checked. 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 {{notificationsCustomFiltersPreferences/}} in its table, and its screenshot shows the email preferences macro. The example used for the other criteria is {{notificationsCustomFiltersPreferences user="XWiki.Admin" /}} . |
| I1 pattern | OK | compared with children, the reference generator: from the Quick Actions menu, entry "Notifications Custom Filters Preferences" found with "notif" or "custom filters", the macro is inserted without a dialog. 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 {{notificationsCustomFiltersPreferences/}} , which shows the description, the Add filter button and a table with the line "(No entries)" in view mode, with no error. An empty table is not nothing. In the editor the table does not appear, see E1. |
| 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. |
| E1 wysiwyg | KO | in the editor, after the insertion and after reopening the page, the macro box shows its description, the Add filter button and a loading spinner. The check of the evidence stopped after 8 seconds, so it was repeated on a saved page with the example, reopened in the editor: after 2, 8, 15 and 30 seconds the box still shows the spinner, and the table, which view mode shows at once, never appears. The user cannot see in the editor whether the filters exist or what the macro will display, and there is no semantic replacement for the table. The same happens for notificationsSystemFiltersPreferences. The macro box itself is a live rendering and not a generic "macro:notificationsCustomFiltersPreferences" placeholder. |
| E2 errors | KO | invalid values are accepted silently. {{notificationsCustomFiltersPreferences target="maybe"/}} , target="" and the wrong case target="WIKI" show the same table as the valid values, with "(No entries)" and no message, but the add, enable and delete actions of the table send the target to the notification preference service, which only accepts "user" and "wiki", so the first change fails. user="xwiki:XWiki.NoSuchUser" , user="XWiki Admin" and user="abc" , which is read as XWiki.abc, show the table of a user that does not exist with no message. The request of the table for the user that does not exist is answered with a 200. The change itself was not run, to leave the filters of the audit instance as they are. user="" shows the error "The given user reference is not supported, only DocumentUserReference are supported for now.", which does not name the parameter. |
| E3 nesting | KO | in a list item and in a table cell, * {{notificationsCustomFiltersPreferences/}} , the macro shows "The [notificationsCustomFiltersPreferences] macro is a standalone macro and it cannot be used inline. Click on this message for details." 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 table with a button, 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 |
|---|---|---|---|---|---|---|---|---|---|---|---|
| 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 filter preferences. This parameter is optional, default value is the context user. Note that for using this parameter, the context user needs administrator right on the given user reference." It 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. |
| target | OK | OK | OK | KO | OK | OK | N/A | KO | OK | N/A | C1: the description is "Target of the macro (could be "user" for the given user or "wiki" for the current wiki)". It lists the two valid values, so the technical name is explained, but it does not say that "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 custom filters 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. |
Other notes
Outside the criteria: 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, as for notificationsEmailPreferences. The page Notification Settings Macros, the documentation of the five settings macros, was not found by the audit of notificationsEmailPreferences, which recorded that no documentation exists.
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 | |
| E1 | E1 wysiwyg | XWIKI-25468 | |
| E2 | E2 errors | XCOMMONS-3847 (partial), XRENDERING-823 (partial), XWIKI-25468 | |
| E3 | E3 nesting | XWIKI-25468 | |
| C1:user | C1 clarity, user | XWIKI-25468 | |
| C4:target | C4 input-assistance, target | XWIKI-25468 | |
| C8:target | C8 advanced, target | 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:user C4:target C8:target D2 D3 D4 E1 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.
