context

Last modified by Lucas Charpentier on 2026/10/27 10:27

Audit

Macro ID
context
Source
XS
Type
Wrapper
Classification reason
Wrapper: most of the output is the content the user types, executed as if another page were the current one, like the script macros and html. The advanced source parameter can take the content from a variable instead, a generator-like use that is rarer.
Status
Reviewed
Criteria version
15.20
XWiki version
18.8.0
Audit date
2026-10-20
Auditor
Compared macros
html code

Sources

Where to gather the information the criteria are checked against, see Gather the sources.

SourceWhat it givesUsed forWhere
DocumentationParameters, default values and examples, including the most common exampleL2, L3, and the criteria measured with the most common examplehttps://extensions.xwiki.org/xwiki/bin/view/Extension/Context%20Macro#HUsage
Source codeHow the macro declares its parameters and content: types, groups, features, advanced and hidden flags, constraints, content type, inline supportC4, C5, C7, C8, C9, C13, E4, E6https://github.com/xwiki/xwiki-platform/tree/master/xwiki-platform-core/xwiki-platform-rendering/xwiki-platform-rendering-macros/xwiki-platform-rendering-macro-context
Macro descriptorWhat the Edit Macro dialog is built from, on design.xwiki.orgD1, D2, C1 to C9, E4Descriptor, list of macros with their categories
TranslationsThe name, description and parameter names in each languageD1, D2, D4, C1l10n.xwiki.org
Uses in XWiki pagesHow XWiki itself uses the macro, a realistic example when the documentation has noneL3, C2, C3, C6, C8, C9Search the xwiki organization on GitHub
Compared macrosThe audits of the macros of the same typeL1, D3html, code
Other sources specific to this macro
CriterionResultNotes
D1 wordingKOminor: the audit treats it as a developer macro, since its only category is Development, but "Context" is generic and does not say what the macro does: it runs its content as if another page were the current one. The documentation describes it as "Executes content with another document set as the current document", which is clearer than the name, like the generic name of the Display macro.
D2 summaryKOminor: the description "Executes content in the context of the passed page." repeats the name, "Context", and only adds "the passed page", which is a programming term. The first sentence of the documentation, "Executes content with another document set as the current document", says more. The Include and Display macros have a description that says what they add to the page.
D3 categoryOKDevelopment only, like html, the first compared macro; code is in Formatting. Developers look for a macro that changes the execution context under Development, so no other category is needed.
D4 quick-actionKO"context" and "Context" give the Quick Actions entry "Context" first, and the Insert Macro dialog finds it first too. The French "Contexte" gives "Contexte" first. The four synonyms of the audit, "render in page context", "run in other document", "page context" and "render document", give no result in the Quick Actions menu nor in the Insert Macro dialog.
L1 consistencyOKcompared with html and code, the wrappers of the same kind that take code or text as content. Like code, the content is optional, since the source parameter can replace it. Unlike html and code, which open the Edit Macro dialog from their Quick Action, context is inserted right away like warning, the reference wrapper, see I1. The differences are by design.
L2 doc-parametersKOthe parameters are documented only in a list of the Usage section of the legacy extensions.xwiki.org page, https://extensions.xwiki.org/xwiki/bin/view/Extension/Context%20Macro, not in the new documentation. The list has no table, does not mention the content, and does not say that CURRENT is the default of transformationContext. The default of restricted, false, is stated.
L3 doc-exampleOKthe audit uses Example 2 of the documentation, {{context document="OtherSpace.OtherPage"}}[[SomeOtherPage]]{{/context}} , with the page replaced by an existing one, as the most common example: it is the first one that renders without error, and it shows the use the description announces. The examples render, but they point at pages that do not exist on a fresh wiki and the page shows no result of any of them. The XWiki sources mostly use restricted and source instead, for example {{context restricted="true" source="script:tip"/}} , which no example shows.
I1 patternOKcompared with warning, the reference wrapper. The Quick Action "Context" inserts the macro right away, without a dialog, like warning, and there is no second Quick Action entry for it. The cursor does not go into the content, see I4.
I2 zero-configKOminor: from the Quick Actions menu, the macro is inserted as {{context/}} , and submitting the Edit Macro dialog with the default values gives {{context}}{{/context}} . Both show only the generic placeholder "macro:context" in the editor, which does not say the result is empty, and render nothing at all in view mode, with no error. The user expects to see what they inserted.
I3 instantOKinserting from the Quick Actions menu with "/context" and Enter inserts the macro in the page right away, without the Edit Macro dialog.
I4 cursorKOafter the insertion, the macro is a placeholder with no content area: the cursor is not in the content, and the text typed next goes outside the macro. The content can only be given through the Edit Macro dialog, see E6.
I5 focusN/Anot applicable to a wrapper.
E1 wysiwygOKthe most common example looks the same in the editor and in view mode, the link SomeOtherPage with its missing page mark. An empty macro, {{context/}} , shows only the generic "macro:context" placeholder in the editor, also after reopening the page, see I2 and E5.
E2 errorsKOinvalid values are accepted silently or give a message that does not name the parameter. {{context restricted="maybe"}}...{{/context}} is read as false and renders the content. {{context document="NoSuchSpace.NoSuchPage"}}...{{/context}} and {{context document="a b:c"}}...{{/context}} render the content with no message, since the document is a plain string that is never checked. {{context source="nocolon"/}} renders "nocolon", the text itself, with no message. {{context transformationContext="abc"/}} gives "Unable to convert value [abc]. Allowed values are (case insensitive) "CURRENT", "DOCUMENT" or "TRANSFORMATIONS"." and an unknown type of source, source="foo:bar" , gives "Unsupported source type [foo]", both clear but neither names the parameter. A wrong case, transformationContext="Document" , is accepted as documented.
E3 nestingOKthe example renders and behaves like at the top level of the page in a list item, in a table cell and in a box. A list, a table and a box inside its content all render in view mode with no error, and nothing is dropped. None of them can be edited in the editor, since the content is not edited in place, see E6.
E4 inline-supportOKthe macro declares inline support, and Before {{context document="MacroAudit.ContextFixture"}}x{{/context}} inline renders on the same line in the editor and in view mode, with no error.
E5 emptyKOan empty macro stays visible as the "macro:context" placeholder, but clicking it only selects the widget: the cursor never enters it and typed text is not inserted. Counted with I4.
E6 inplaceKOthe content is never edited in place: the editor shows the rendered result, and changing the content needs the Edit Macro dialog, where it is a plain text area with no editing aid, also for an existing macro. For example, double-clicking the link of the most common example opens the dialog with "SomeOtherPage" in the Content text area. XWIKI-19978 asks for it.

Parameters

ParameterC1 clarityC2 mandatoryC3 defaultsC4 input-assistanceC5 groupsC6 orderC7 alternativesC8 advancedC9 technicalC13 constraintsNotes
$contentOKOKN/AOKN/AOKN/AN/AN/AN/A

C1: "Content" with "The content to execute" is enough for a developer macro. The description does not say that the source parameter can replace it.

C2: not mandatory, since the source parameter can give the content instead.

C4: a plain text area in the Edit Macro dialog, counted under E6.

C6: first in the dialog, which is the order of the most common example.

documentKOOKOKOKOKOKN/AOKOKN/A

C1, minor: the description "The reference to the page the content will be executed in." does not say what an empty value does, although both calls of the XWiki sources outside the tests leave it empty and keep the current page, like {{context restricted="true" source="script:tip"/}} .

C4: a page picker that shows the title of the chosen page, "Context fixture page" for the audit page. The macro itself takes a plain string and accepts any value, see E2.

C6: first after the content, and set by the most common example.

restrictedOKOKOKOKOKOKN/AOKOKN/A

C1: "Indicate if the content should be executed in a restricted context." uses a technical term, which is acceptable for a developer macro. The French name and description are left in English, which is a translation matter, not recorded here.

C8: not advanced, and set by two of the real calls of the XWiki sources, like {{context transformationContext="document" restricted=true}} .

sourceKOOKOKKOOKOKOKOKOKN/A

C1, minor: the description "the reference of the content to insert (e.g. string:bold, script:myvariable)" gives two examples of the "type:value" syntax but does not list the other types, and does not say that the source replaces the content. The error "Unsupported source type [foo]" is the only way to learn the other types. The French name and description are left in English, a translation matter.

C4: a free text field for a typed reference, with no picker for the types that could have one, like a page: the user has to know the syntax. Some types, like script:, cannot have a picker, so a proper field needs design work, as for the code macro.

C7: the source and the content are alternative ways to give the content, but the Edit Macro dialog cannot present them as one choice, since only parameters can be part of a feature. A limitation of the macro system, listed in the Cross-macro findings, reported as XWIKI-25456.

C8: advanced, as it is used by a minority of the calls, like {{context restricted="true" source="script:tip"/}} .

transformationContextKOOKOKOKOKOKN/AOKOKN/A

C1: the dialog shows the name "TransformationContext" in camel case, and the description "The Transformation Context mode to use. Valid values are "current", "document" and "transformations"" repeats the name and lists the values without saying what each one does, or which one to pick: the three modes change which XDOM the macros inside the content see, and "transformations" executes the macros of the other page. The documentation explains them, the dialog does not. The values appear as "Current", "Document" and "Transformations" in the select, while the description writes them in lower case.

C3: Current is preselected, the declared default.

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.

KOCriterionExisting ticketsNew tickets
D1D1 wordingXWIKI-25477
D2D2 summaryXWIKI-25477
D4D4 quick-actionXWIKI-25444
L2L2 doc-parametersXINFRA-525
I2I2 zero-configXWIKI-25567
I4I4 cursorXWIKI-25569
E2E2 errorsXCOMMONS-3847 (partial), XRENDERING-823 (partial), XWIKI-25578 (partial)
E5E5 emptyXWIKI-25567
E6E6 inplaceXWIKI-25443 (partial), XWIKI-25567
C1:documentC1 clarity, documentXWIKI-25477
C1:sourceC1 clarity, sourceXWIKI-25477
C4:sourceC4 input-assistance, sourceXWIKI-25575
C1:transformationContextC1 clarity, transformationContextXWIKI-25477
Success

Every KO is covered by a ticket.

Tickets

TicketOriginKOs coveredKOs partly covered
XCOMMONS-3847NewE2
XRENDERING-823NewE2
XWIKI-25443NewE6
XWIKI-25444NewD4
XWIKI-25477NewC1:document C1:source C1:transformationContext D1 D2
XINFRA-525NewL2
XWIKI-25567NewE6 E5 I2
XWIKI-25569NewI4
XWIKI-25575NewC4:source
XWIKI-25578NewE2

Known issues of this macro

IssueTitleStatusCriteria
XWIKI-15190Raise an error when the {{context}} macro is used inline but produces non inline BlocksOpenE4

68 more known issues affect every macro: see the Known issues.

Get Connected