Context Macro

Version 10.1 by Vincent Massol on 2021/03/17 17:20

cogExecutes content with another document set as the current document
TypeJAR
Category
Developed by

XWiki Development Team

Rating
0 Votes
LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Standard

Compatibility

XWiki Enterprise >= 3.0M1

Description

Useful when you need to have wiki markup executed as if they were located in another document. This means, for example, that links and image references are computed against the other document as the base for resolving relative references. Macros also execute in the context of the other document (e.g. the TOC macro would generate a TOC based on headings from that other document).

The Include Macro also provides a similar feature but instead, it copies the content of the referenced document inside the current document. Note that the Display Macro is bit different too since it renders the content of the referenced document in that document's context and include the rendered content in the current document.

Usage

{{context document="wiki:space.page" [transformationContext="current|document|transformations"]}}
... content in wiki syntax here...
{{/context}}

where:

  • document: reference to the document to use as the base
  • Since 8.3 transformationContext: Defines the strategy to use for setting the Transformation Context for the Context Macro. Namely this controls the context for the macros located inside the Context Macro. For example some macros will use as input the other XDOM elements before or after the current Macro block that they correspond to. For example the TOC macro executes late (with a low priority) so that all other macros have a chance to execute and then it looks for all Heading Blocks in the XDOM, from the root. Valid values:
    • current: The XDOM on which the macros in the Context macro execute is the current document's XDOM.
    • document: The XDOM on which the macros in the Context macro execute is the referenced document's XDOM (but without transformations applied to that XDOM).
    • transformations: The XDOM on which the macros in the Context macro execute is the referenced document's XDOM but with transformations applied to that XDOM. IMPORTANT: This can be dangerous since it means executing macros, and thus also script macros defined in the referenced document. To be used with caution since that have side effects.

Example 1

The following will display a link to OtherSpace.SomeOtherPage, whereas without the context macro it would display a link to Space.SomeOtherPage (if the current document using the context macro is located in a space named Space):

{{context document="OtherSpace.OtherPage"}}
[[SomeOtherPage]]
{{/context}}

Example 2

Imagine you have an XWiki Object located in a Main.OtherPage document and that Object has an Icon field using the format attach:image.png. Imagine also that Main.OtherPage is using velocity scripting to extract the icon field and to display it on the page. This would fine since image.png would be a file attached to the page. Now imagine that in Main.Page we'd also want to display that icon. Since it's not defined in an absolute manner (that would be attach:[email protected]) it would fail to be displayed unless we used:

{{context document="Main.OtherPage"}}
{{velocity}}
image:$icon
{{/velocity}}
{{/context}}

Example 3

Since 8.3 The following will generate in the current document a TOC (Table Of Content) based on headings from the Main.OtherPage document.

{{context document="Main.OtherPage" transformationContext="document"}}
{{toc/}}
{{/context}}

Note that if you wish to also include generated Headings (i.e. headings generated by the execution of macros), you'd need to use:

{{context document="Main.OtherPage" transformationContext="transformation"}}
{{toc/}}
{{/context}}

However be aware that this means that the macros located inside Main.OtherPage will execute so make sure it doesn't have any side effect.

Tags:
    

Get Connected