You are viewing an old version of this page. View the current version.
Compare with Current
View Page History
« Previous
Version 31
Next »
Transcludes content from a document marked with the content marker macro.
The Transclusion Macro includes content from another page at render time. Transclusion supports single sourcing.
The content to be transcluded has to be marked as a section (Section Macro) or region content (Content Marker Macro).
The body provides space for replacements of the form "placeholder=replacement", each on its own line. Specify a placeholder like this ${placeholderName}.
Properties
Document
The Confluence page from which to transclude content. As this field is mandatory you have to enter the page from which to transclude content. In the case of transcluding content from the current page combined with a theme like the ones provided by Brikit Theme Press for Confluence you can use @self as the name of the page to indicate that the content shall be transcluded from the page that uses this layout.
The following graphic illustrates the usage of @self.
Cannot find content to transclude!
Please check the reference (ids=Summary / tags=) to the document 'Graphic to Illustrate the @self use-case' to transclude from.
If you want to silence this message on missing content, check 'Missing Content Message'.
Please refer to the Transclusion Macro documentation for more information about this macro.
Identifiers
The identifiers of marked content or sections to include.
Usually only one identifier is used to include one content, but it need not to be only one.
The identifier of a section defaults to its title.
To control the rendering you have the following options (available since version 1.8.0):
| Option | Description | Example |
|---|
- | Suppress the rendering of the section title. | -Description |
! | Suppress the section. | !Description |
Since version 1.17 it is possible to positively include all markers. This is necessary in case titles for selected sections need to be suppressed, but should not indicate that this is a selection.
Target Heading Level
Specifies the new base level of the transcluded fragment. The top-level heading will be set to this level and subsections are transformed accordingly.
This modifier allows to render a section with subsections within another page adjusted to the target's heading level.
The Target Heading Level may be set to '*'. In this case the level is calculated depending on the location of the macro. If the parent is a section at level X, the target level will be set to X+1.
Impersonate
The Impersonate Feature allows to define a template that is rendered in the context of the transcluding document.
If checked the transcluding document is used to render the content of the transcluded document.
See Impersonator - using Live Templates for a tip on using this feature.
Apply Document Properties
If Apply Document Properties is checked properties of the document and space are applied as placeholders.
Transitive Transclusion
If Transitive Transclusion is checked then transclusion from transcluded content is allowed.
Otherwise the transclusion macros only have access to fragments that are physically part of the document.
Select
Specify a comma-separated list of page properties from the transcluded document to be rendered in a table. You may also specify section names.
Use Deep Link to select a property from a referenced document in the Select Clause.
The table header can be replaced using the Header Translations parameter by most macros
Audience->Group=Group Name
Force Show
If checked then content that is hidden in its original location is shown.
This effectively overrides the hide parameter of a Section Macro or Content Marker Macro.
Render Reference Box
If checked, a box that marks the transcluded text is rendered with a link to the part in the document (if the transcluded part is uniquely identifiable).
Here is an example of transcluded content from an example page named "A Document":
If you click on the name you jump to the document of the transcluded content.
A transclusion box is a handle, typically only available to users who actually have write access to a page, to quickly jump to the page from which content is transcluded.
The rendering can be controlled via space property render-transclusion-box.
The following values are valid:
only-with-edit-permissionThe reference box is only rendered, if the user has edit permission. That is the user is an other and benefits from the clue of transcluded content.
never- The reference box is never rendered. This may proof useful for authors that want to check the appearance without boxes.
Missing Content Message
If unchecked, no message will be rendered, if no content is to be transcluded.
Usually maintainers of the documentation site require to take notice of missing transclusions. So if this option is checked (per default), a warning message will be rendered on missing content.
Name as Heading
If checked renders the name of the transcluded document as heading. Requires target level to be set to a value between 1 and 6.
Represents Document
If checked the transcluded content represents the referenced document. Use if Names as Heading is not selected, but the contents represents the document.
When this option is selected, localized links pointing to a document (with a link without an anchor) will target this section. Authors must only tag one transclusion to represent a document per page.
Localized links are supported by the Section Macro and the Content Marker Macro.
Suppress Selection
Transclusions may slow down the rendering process. To help authors to speed up rendering, the space property Suppress Transclusion helps to suppress transclusions. This allows to render the properties table without actually transcluding sections from the page.
If this box is checked, the specified Select is only applied if the space is suppressing transclusions.
No Cache
If checked the macro will not use the page fragment cache to calculate the transcluded page fragment.
This does only apply if the space is using the transclusion cache. Otherwise the state of the checkbox has no effect.
If the macro uses placeholders, caching will automatically switched off.
Identifier
The identifier is rendered with the encosing HTML element.
It is also useful to uniquely identify the macro in a page.
Remote Controls
List of controls to pass to transcluded contexts. Controls are separated by ampersand ('&').
This allows to control the rendering of remote controllable macros by sending controls. For more information please refer to Remote Control.
Macro Body
Specify the replacements in the macro's body.
The transcluded content may specify placeholders in the form ${placeholder-name}.
Placeholder/replacement pairs identify the placeholder to be replaced by its name and content for the replacement of the placeholder.
Before version 4.8 the body of the macro only accepts plain text. Therefore only plain text replacements were supported.
Since version 4.8 the body accepts rich text. Users may specify replacements in both forms.
Plain Text Replacements
Switch the body to preformatted and specify key/value pairs in plain text form.
Here is a sample key/value list in text form.
placeholder-name=Replacement 1
Another Placeholder Name=Replacement Text Two
Everything before the first equal sign ('=') is considered to be the key for the placeholder, everthing after the equal sign up to the end of the line is the value.
Rich Text Replacements
To replace a placeholder with an HTML element, add a table with two columns.
Only lines with table data are parsed. The table header is purely to guide authors and may not be specified at all.
Details
Remote Controlled Documents
Remote Controlled Documents allow to control the content at request time. A HTTP request may override parameters of the transclusion macro. A request parameter addresses a transclusion macro by its identifier. After the identifier the name of the parameter is appended, separated by a colon.
The list of parameters allowed to override:
documentidstagsselecttaget-heading-level (yes, the 'r' is missing!)render-document-name-as-headingapply-document-propertiesrender-error-on-no-contentremove-template-buttons
Search Transcluding Pages
To search for pages that transclude information from a given document, use the following search syntax:
macroName:projectdoc-transclusion-macro* AND ("{Title of transcluded page}")
This will return all pages that are using the transclusion macro and have the title on their page content.
If you are using documentation modules, the pages transcluding the module will be displayed automatically.
Transcluding Content with identical Titles
If you have a document with identical titles, it is still possible to transclude the individual sections. Confluence ensures that each heading on a page is unique. This is required by the HTML 5 standard. projectdoc use this service to also make sections unique. Therefore a title that occurs a second time on the same page is suffixed with '.1'. The next with '.2', '.3', and so on.
Here is the page with two sections titled 'Content'.
Here is the macro editor selecting the content of the second section titled 'Content' by selecting on 'Content.1':
Resources
Transclusion Macros
A list of macros supporting transclusion or embedding of contents provided by Atlassian:
