Include Macro
 | Include an entity (document, property, etc.) |
| Type | JAR |
| Category | Macro |
| Developed by | |
| Rating | |
| License | GNU Lesser General Public License 2.1 |
| Bundled With | XWiki Standard |
Table of contents
Description
Include other pages into the current page. By default this macro acts as if the included content was copied in the including page (e.g. if you include a page with relative links to images, they won't be found since they won't exist in the including page). If, instead you wish to include the result of what you get when you view the included page, use the display macro instead.
Usage
From WYSIWYG Editor
From Wiki Syntax
Parameters definition
| Name | Optional | Allowed values | Default value | Description |
|---|---|---|---|---|
| page | no or reference | A page reference | XWiki 10.6+ The reference of the page to include. You should use this parameter rather than the reference one which is more complex to use. | |
| reference | no or page | an entity reference | The reference of the entity to include. See the Model module to understand the concept of references. | |
| type | yes | document | document | The type of the entity. This parameter is also only useful when used with the reference parameter. It's not needed when using the page parameter. |
| section | yes | string | The id to the Heading section to include in the target document. To do that you'll need to find out the id that is automatically generated by XWiki. To find it you have 2 solutions:
Note that in the future we plan to improve it. | |
| excludeFirstHeading | yes | true or false | false | XWiki 12.4+ If true, exclude the heading from the included page if the first element of that page is a heading. |
| author | yes | auto/current/target | auto | XWiki 14.10.2+ Indicate the author to use to execute the content |
| document | no | a wiki document | The name of the document to include. | |
| context | yes | new/current | current | Defines whether the included page is executed in its separated execution context or whether it's executed in the context of the current page. |
Author
XWiki 14.10.2+ When context=current (the default) it's possible to control which author should be used for the execution of the included content:
- target: the inlude macro execute right away the content with the author of the target document content
- current: the include macro just parse the content but does not execute it, it will be executed as if it was part of the content where it's been inserted (which means it will be executed with the right of the top level content author)
- auto (the default):
- XWiki <15.0 behave like current
- XWiki 15.0+ behave like current if the target document content author has programming right, target otherwise
Examples
Example 1:
Example 2 (if you want to include a page from another wiki):
Example 3:
Example 4 (using the reference parameter):
NOTE: Be sure to include the / within the "/}} at the end, otherwise any content that comes after the included section on this page will fail to appear.
Including velocity macros
To include the macros of another page for use in this page use something as follows:
{{velocity}}
The #macros() and $variables of the Macros page are now visible.
{{/velocity}}
NOTE: The include macro must be outside the velocity macro and before it as a page with some velocity is always first parsed for its external wiki syntax; meeting a velocity block then produces the wiki syntax which is parsed afterwards. This would mean that using the include macro inside velocity would trigger the inclusion only after the velocity code is finished.
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-include 16.10.1):
- org.xwiki.commons:xwiki-commons-context 16.10.1
- org.xwiki.platform:xwiki-platform-bridge 16.10.1
- org.xwiki.platform:xwiki-platform-model-api 16.10.1
- org.xwiki.platform:xwiki-platform-display-api 16.10.1
- org.xwiki.platform:xwiki-platform-rendering-macro-context 16.10.1
- org.xwiki.platform:xwiki-platform-rendering-transformation-macro 16.10.1
- org.xwiki.platform:xwiki-platform-rendering-xwiki 16.10.1
- org.xwiki.rendering:xwiki-rendering-api 16.10.1
- org.xwiki.rendering:xwiki-rendering-transformation-macro 16.10.1
