uiextension
Audit
- Macro ID
- uiextension
- Source
- XS
- Type
- Generator
- Classification reason
- The macro has no content and its output is the rendering of the UI extension whose identifier is given, so it is classified as a generator.
- Status
- Reviewed
- Criteria version
- 15.20
- XWiki version
- 18.8.0
- Audit date
- 2026-10-20
- Auditor
- Compared macros
- include translation
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 | "UI Extension" is the name XWiki gives to the feature, the UI extension points that applications fill, so it is right for a macro of the Development category, like Live Data for its feature. |
| D2 summary | KO | "Insert a UI extension." repeats the name and does not say what the macro adds to the page: the output of the UI extension registered under the given identifier, rendered where the macro is. The French and German descriptions repeat the name the same way. To reproduce: open the Insert Macro dialog and select UI Extension. |
| D3 category | OK | Development, the category of the macro, where a developer who wants to render a UI extension looks for it. The compared macros include and translation are in Content, which fits their user use; this macro needs the identifier of a UI extension, which only developers know. |
| D4 quick-action | OK | Quick Actions finds the macro first for "uiextension", "UI Extension", "extension", "ui extension" and the French name "Extension UI", each time with UI Extensions, the sibling macro, second. The synonyms "uix" and "insert extension" give no result. The macro is named after its technology, so the few synonyms are OK. |
| L1 consistency | OK | compared with include and translation. Like them, the macro has no content, one mandatory target and no other parameter, so its Quick Action and the Insert Macro dialog open the Edit Macro dialog, which is by design. |
| L2 doc-parameters | KO | the only parameter, id, is documented only on the legacy extensions.xwiki.org page, https://extensions.xwiki.org/xwiki/bin/view/Extension/Extension%20Module/UI%20Extension%20Macro/, not in the new documentation. That page describes it as "The identifier of the UI extensions to insert" and says nothing on what a UI extension is or where to find the identifiers. |
| L3 doc-example | KO | the only example of the documentation, {{uiextension id="org.xwiki.platform:xwiki-platform-search-ui"/}} , renders the error "Failed to find an extension id id [org.xwiki.platform:xwiki-platform-search-ui]": it gives the Maven identifier of an extension of the Extension Manager, not the identifier of a UI extension. So no example shows the most common use, which in XWiki Standard passes the identifier of an extension found in a loop over an extension point, like {{uiextension id="$services.rendering.escape($uix.id, 'xwiki/2.1')"/}} . The audit uses the literal call of XWiki Standard that renders, {{uiextension id="org.xwiki.platform.security.requiredrights.ui.RequiredRightsInfoUIExtension"/}} , which shows the "Required rights" block of a page that enforces no right. |
| I1 pattern | OK | compared with children, the reference generator, and with include and translation. From Quick Actions, the "UI Extension" entry opens the Edit Macro dialog, since the identifier is mandatory, the generic behavior of a generator that needs a target. The Insert Macro dialog opens the same dialog. |
| I2 zero-config | OK | submitting the Edit Macro dialog with the empty mandatory identifier keeps the dialog open with no message, the generic behavior of the dialog. {{uiextension/}} typed in the source gives "Invalid macro parameters used for the [uiextension] macro. Cause: [Property [id] mandatory].", acceptable for a generator that needs its target. A UI extension that exists but renders nothing gives an empty result, with only the generic "macro:uiextension" text in the editor, like include for an empty page. |
| I3 instant | N/A | |
| I4 cursor | N/A | |
| I5 focus | OK | the mandatory Identifier field is alone in the dialog, visible without scrolling, and has the focus when the dialog opens. |
| E1 wysiwyg | OK | the example shows the "Required rights" block in the editor as in view mode, under a small "Uiextension" label, also after reopening the page. |
| E2 errors | KO | an empty identifier is accepted silently: {{uiextension id=""/}} renders nothing, with no message, since the dialog refuses it but a page can hold it. An unknown identifier, a wrong case, an extension point identifier or a value with a space gives "Failed to find an extension id id [org.xwiki.nosuch.Extension]", which repeats "id" and speaks of an extension id, as the Extension Manager does, instead of a UI extension identifier. |
| E3 nesting | OK | the example renders with no error in a list item, a table cell and a box. It is a block output that stays usable, and the macro has no content. |
| E4 inline-support | OK | the macro declares inline support. Before {{uiextension id="org.xwiki.audit.hello.uix"/}} after. , for a UI extension whose content is a single line, renders on the same line. A UI extension with several blocks, like the example, breaks the sentence, which depends on the chosen UI extension. |
| E5 empty | N/A | |
| 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 |
|---|---|---|---|---|---|---|---|---|---|---|---|
| id | OK | OK | OK | KO | OK | OK | N/A | OK | OK | N/A | C1: "The unique identifier of the UI extension to insert." says what the value is, and the technical terms are OK for a developer macro. It does not say where the identifiers come from, which the documentation does not say either, see L2 and L3. C2: mandatory with no default, which is right: without an identifier, there is nothing to insert. C3: no default makes sense, the identifier names one UI extension. C4: a plain text field, so the developer has to know the exact identifier, case included: a typo gives an error, see E2. A picker of the UI extensions of the wiki, with their extension point, could be used, like the key picker asked for translation. C13: N/A, an identifier is any text, checked when the macro renders; the missing picker is counted under C4. |
Other notes
Other notes: a UI extension is declared by a wiki object or a component and attached to an extension point. The macro renders one of them by its identifier, where the sibling macro uiextensions renders all the UI extensions of an extension point. Both share the same Development category, the description pattern and the documentation page style.
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-25477 | |
| L2 | L2 doc-parameters | XINFRA-525 | |
| L3 | L3 doc-example | XINFRA-526 | |
| E2 | E2 errors | XCOMMONS-3847 (partial), XRENDERING-823 (partial), XWIKI-25501 (partial) | |
| C4:id | C4 input-assistance, id | XWIKI-23045 (partial) | XWIKI-25501 |
Tickets
| Ticket | Origin | KOs covered | KOs partly covered |
|---|---|---|---|
| XCOMMONS-3847 | New | E2 | |
| XRENDERING-823 | New | E2 | |
| XWIKI-25477 | New | D2 | |
| XWIKI-23045 | Existing | C4:id | |
| XWIKI-25501 | New | C4:id | E2 |
| 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.
