Executes content with another document set as the current document

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).

Usage

where:

• document: reference to the document to use as the base, it's optional since 15.0
• XWiki 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.
• XWiki 15.0+, 14.10.4+ restricted: false by default, if true execute the content in a restricted context
• XWiki 15.1+, 14.10.5+ source: indicate the reference of a source to use to get the content instead of passing it as macro content

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):

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:Main.OtherPage@image.png) it would fail to be displayed unless we used:

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.

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

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.

Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager).

You can also use the manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.

Dependencies

Dependencies for this extension (org.xwiki.platform:xwiki-platform-rendering-macro-context 16.9.0):

• org.xwiki.platform:xwiki-platform-rendering-async-macro 16.9.0
• org.xwiki.platform:xwiki-platform-security-requiredrights-macro 16.9.0
• org.xwiki.platform:xwiki-platform-rendering-transformation-macro 16.9.0
• org.xwiki.rendering:xwiki-rendering-api 16.9.0
• org.xwiki.rendering:xwiki-rendering-transformation-macro 16.9.0