groovy
Audit
- Macro ID
- groovy
- Source
- XS
- Type
- Generator
- Classification reason
- Generator, like the other script macros: the output is what the script computes, far from the code typed in the content, which the reader never sees. The parameters only change how the script runs and how its output is processed.
- Status
- Reviewed
- Criteria version
- 15.20
- XWiki version
- 18.8.0
- Audit date
- 2026-10-20
- Auditor
- Compared macros
- velocity python
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 | "Groovy" is the name of the technology, and the macro is audited as a developer macro, in the Development category, so the name is fine. The French and German names are "Groovy" too, like velocity. |
| D2 summary | OK | "Execute a groovy script." says what the macro does, and for a generic script macro this is enough, like "Fetches information from a JIRA server". It does not say that the output of the script is inserted in the page as wiki syntax, which the output and wiki parameters tell. |
| D3 category | OK | only Development, where users look for a script macro, like html and velocity. |
| D4 quick-action | OK | Quick Actions finds the macro first for "groovy" and in second place for "script" and "execute", behind Script and Async macro. "java", "run code", "program" and "eval" do not find it. The French and German names are the same as the English one, so only the English name, the ID and two synonyms are checked. A technical macro named after its technology is OK even when few synonyms find it, like html. |
| L1 consistency | OK | compared with velocity and python, the other script macros, which also take a mandatory script as content: the Quick Action opens the Edit Macro dialog with a required Content text area, and the macro declares inline support. The wiki parameter defaults to true, like them, since the output of a script is wiki syntax. |
| L2 doc-parameters | KO | the parameters are documented only on the legacy extensions.xwiki.org page, https://extensions.xwiki.org/xwiki/bin/view/Extension/Groovy%20Macro, not in the new documentation. The content and jars are not documented, output is only mentioned in a sentence and wiki is not described, and the page refers to the Script Macro page for details. |
| L3 doc-example | KO | minor: the first example, a loop over a list printing wiki list items, shows the plain use and renders "one" and "two", so it is used as the most common example. The "Parameters definition" shows the incomplete fragment {{groovy output="false"}} with no script and no closing tag, which cannot be reproduced in the editor, and the Example section repeats the first example word for word. |
| I1 pattern | OK | compared with the reference generator, children. The Groovy Quick Action opens the Edit Macro dialog with an empty Content text area, and the macro needs its script to do anything, so the dialog is OK, like include and the other script macros. |
| I2 zero-config | OK | submitting the dialog with an empty content keeps it open with no message, the generic behavior of the dialog for a mandatory value. A {{groovy/}} written in the source renders nothing, with no error, which is the expected result of an empty script. |
| I3 instant | N/A | N/A for a generator. The Quick Action opens the Edit Macro dialog with an empty Content text area, see I1. |
| I4 cursor | N/A | N/A for a generator. After submitting the dialog, the macro widget is selected, and the script can only be changed through the dialog. |
| I5 focus | OK | the content, the script, is the only mandatory parameter: the Edit Macro dialog shows its text area first, with the focus in it, and every field is visible without scrolling. |
| E1 wysiwyg | OK | with a script that prints text, the editor shows its rendered output, the two list items "one" and "two" for the first example, the same as in view mode. A script with no output, like output="false", {{groovy/}} or only an assignment, shows the generic placeholder "macro:groovy" with no hint of the script. Recorded OK on the most common example, like velocity. |
| E2 errors | KO | invalid values are accepted silently. output="maybe" is read as false and the whole output disappears, wiki="maybe" is accepted and the output is rendered as plain text, and an unknown parameter is ignored, the last one being generic. A jars value with a missing attachment, gives the message "inputStream", which names neither the attachment nor the parameter. A jars value that is not a URL, or a list "a.jar, b.jar" with a space, gives "Failed to add JAR URLs to the current class loader for [...]", a technical message with no hint of the separator. |
| E3 nesting | OK | in a list item, a table cell and a box the macro renders its output with no error. The content is code, so a list, a table or a box typed as the script gives the Groovy syntax error "startup failed ... Unexpected input", which is expected, and the technical message counts under E2. The content is not editable in place in any of these cases. |
| E4 inline-support | OK | the macro declares inline support, and its output renders inside a sentence. A script that outputs block syntax, like a list, gives the usual behavior of wiki syntax in an inline context. |
| E5 empty | N/A | N/A for a generator. The editor shows the output of the script, or "macro:groovy" when it is empty, and the content can only be typed in the Edit Macro dialog. |
| E6 inplace | N/A | N/A for a generator. The script is still edited only in a plain text area of 7 rows of the Edit Macro dialog, with no code editing aid, which is worth an improvement outside the criteria. |
Parameters
| Parameter | C1 clarity | C2 mandatory | C3 defaults | C4 input-assistance | C5 groups | C6 order | C7 alternatives | C8 advanced | C9 technical | C13 constraints | Notes |
|---|---|---|---|---|---|---|---|---|---|---|---|
| $content | OK | OK | N/A | OK | N/A | OK | N/A | N/A | N/A | N/A | C1: the name "Content" and the description "the groovy script to execute" are clear for a developer macro. C2: the content is mandatory, which is right, an empty script does nothing. C4: a plain text area in the Edit Macro dialog, counted under E6. C6: the content comes first, before the optional parameters. |
| jars | OK | OK | OK | KO | OK | OK | N/A | KO | OK | KO | C1: the name is the ID, and the description with its example is clear for a developer macro. It says "List of JARs" without saying how to separate several values. C2: optional, which is right. C3: empty means no extra JAR, which is the right default. C4, minor: a free text field for attachment references or URLs, with no picker, and a missing attachment gives the unclear message "inputStream", see E2. The values are free text, so the KO is minor. C8: a rarely used parameter, set by no example of the documentation and none of the XWiki Standard calls found, and not marked as advanced. C9: the parameter is inherited from the script macros, and a groovy script can load a Java library on its class loader, so it has a realistic use, even with no documented example. C13: a list of references in a single field with the separator undeclared: "a.jar, b.jar" is refused with "Failed to add JAR URLs to the current class loader" and the description does not say which separator to use. |
| output | OK | OK | OK | OK | OK | OK | N/A | OK | OK | OK | C1: the description "Specifies whether or not the output result should be inserted back in the page." is understandable for a developer macro. The English name is the ID, "output". C3: the checkbox preselects the default, true. C4: a checkbox for a boolean. C6: no common example sets it, and it is visible in the group with only three other fields. C8: output="false" is the documented way to run a script that only defines classes or variables, and is used now and then, so it is not rarely used. C9: realistic use, the documentation sets it. |
| wiki | OK | OK | OK | OK | OK | OK | N/A | KO | OK | OK | C1: the description "Specifies whether or not the script output contains wiki markup." is clear for a developer macro. The English name is the ID, "wiki". C3: the checkbox preselects the default, true. C4: a checkbox for a boolean. C8, minor: wiki="false" is a realistic but rare use, set by no example of the documentation, and the field is not marked as advanced. C9: realistic use, for a script that outputs text with wiki characters. |
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 |
|---|---|---|---|
| L2 | L2 doc-parameters | XINFRA-525 | |
| L3 | L3 doc-example | XINFRA-526 | |
| E2 | E2 errors | XCOMMONS-3847 (partial), XRENDERING-823 (partial), XWIKI-25579 (partial) | |
| C4:jars | C4 input-assistance, jars | XWIKI-25568 | |
| C8:jars | C8 advanced, jars | XWIKI-25476 | |
| C13:jars | C13 constraints, jars | XWIKI-25509 | |
| C8:wiki | C8 advanced, wiki | XWIKI-25476 |
Tickets
| Ticket | Origin | KOs covered | KOs partly covered |
|---|---|---|---|
| XCOMMONS-3847 | New | E2 | |
| XRENDERING-823 | New | E2 | |
| XWIKI-25476 | New | C8:jars C8:wiki | |
| XINFRA-525 | New | L2 | |
| XINFRA-526 | New | L3 | |
| XWIKI-25509 | New | C13:jars | |
| XWIKI-25568 | New | C4:jars | |
| XWIKI-25579 | New | E2 |
Known issues of this macro
| Issue | Title | Status | Criteria |
|---|---|---|---|
| XWIKI-19035 | Groovy Macro Content field appears to be mandatory only on CKEditor UI edit mode | Open | C2 |
68 more known issues affect every macro: see the Known issues.
