"display" Macro
Reference
Description
The display macro shows another page inside the current one.
The displayed page is rendered in its own context, exactly as if you opened it directly: its relative references, its attachments in particular, are resolved from its own location and not from the page displaying it.
Usage
{{display reference="Sales.Reports.WebHome"/}}The macro works inline as well as standalone.
Three behaviours are worth knowing before you use it:
- displaying a page that does not exist renders nothing at all, rather than an error;
- displaying a page you are not allowed to view raises a macro error;
- a page cannot display itself, directly or through a chain of pages: the macro detects the recursion and refuses it.
The editors ask for the page to display, and offer the two optional parameters below it:
Parameters
| Name | Mandatory | Allowed Values | Default Value | Description |
|---|---|---|---|---|
| reference | yes | an entity reference, such as Sales.Reports.WebHome | none | The page to display. Either this parameter or page has to be set. |
| page | yes | a page reference, such as Sales/Reports | none | The page to display, written as a page reference instead of an entity reference. Either this parameter or reference has to be set. |
| type | no | an entity type | document | The type of the entity reference points at. |
| section | no | a heading id, such as HMyHeading | none | Display only that section of the target page instead of the whole page. |
| excludeFirstHeading | no | true or false | false | Leave out the first heading of the displayed page or section, when it starts with one |
Examples
Display a Page
{{display reference="Sales.Reports.WebHome"/}}
Display a Page of Another Wiki
Prefix the reference with the name of the wiki:
{{display reference="intranet:Sales.Reports.WebHome"/}}Display a Single Section
The section parameter takes the id of a heading, which XWiki generates from the heading's title. For a title made only of the characters A-Z, a-z, 0-9, :, _, . and -, that id is H followed by the title with its spaces removed: "My Heading" gives HMyHeading. Any other character is replaced by its hexadecimal Unicode code point, so "Café" gives HCafE9, which is easy to get wrong. To be sure of an id, display the page, look at its HTML source, and read the id attribute of the heading:
<h2 id="HMyHeading" class="wikigeneratedid"><span>My Heading</span></h2>{{display reference="Sales.Reports.WebHome" section="HMyHeading"/}}Display a Section Without Repeating Its Title
When the page already carries a heading of its own above the macro, excludeFirstHeading drops the displayed section's heading so the title is not read twice:
{{display reference="Sales.Reports.WebHome" section="HMyHeading" excludeFirstHeading="true"/}}
