Renders transcluded content fetched from documents of a result set.
With the Transclude Documents Macro document authors transclude from result sets of document queries.
Since the macro requires properties to be set to select on documents, the macro transcludes only from projectdoc documents.
This feature is very convenient if used to transclude child documents, using the Restrict to immediate Children parameter. Consider to use Section documents since they make it easier to define a default sort order (a feature supported by all doctypes of type Subdocument).
Transcluded fragments are easily recognizable by authors (users with page edit permissions). They are surrounded by a Render Reference Box that also renders widgets to quickly open the page transcluded from in edit mode (see Transclude Child Documents for details).
All information is transcluded on request time. Since the macro runs a query, the list of hits is also dependent on request time and the access permissions of the user requesting the page.
Since 2.5
Wiki Markup is supported since version 2.5.
Properties
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.
If the target heading level is set to 2 and the top-level heading is a h1, each heading within the transcluded fragment is incremented by one.
We are referring to the projectdoc Section Macro, not the Confluence Section Macro.
Since version 1.7 (requires Confluence 5.8+) 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.
You typically should not combine a target level of 'blank' with documents using sections (with levels or a '*').
The use of the blank target level may be deprecated in the future.
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.
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.
This is an example for placeholder replacements in the body:
product-name=projectdoc Toolbox product-version=2.0
And this is an example of a fragment that defines the placeholders:
There current version of ${product-name} is ${product-version}.
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
More information to use this macro.
Transclude Child Documents
Its fairly simple to transclude all sections of the child documents. Just check the Restrict to immediate Children checkbox and set the Target Heading Level to '*'. The target level will adjust the section levels of the transcluded documents to fit the level in the transcluding document.
Transclude Child Documents
The example shows two child documents that are transcluded. Note that the box around the transcluded content is only rendered for page authors. This allows them to jump to the transcluded document quickly.
The editor shows the checked restriction on children and the selection of the target heading level.
The screenshot of the parent document shows the transcluded child fragments rendered at level 3 under the level 2 section (arbitrarily) named 'Excerpts'.
If the user has edit privileges, an additional edit widget will be rendered to open the transcluded page in edit mode quickly.
Please note that only sections are transcluded. Therefore you have to define sections in the child documents. If you do not need to transclude all sections, use Identifiers (typically the page titles) and Tags to filter.
