Transcludes content from a document marked with the content marker macro and renders it as plain text.
Properties
The macro provides the following parameters.
Tags
The tags of marked content or sections to include. Multiple elements are added in the order they appear in their document.
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.
Live Templates with Impersonator
The impersonator box has edges on the upper left and lower right corner.
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.
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
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':
Activate Macro
To activate the macro an administrator needs to go to the Add-on page.
Here activate the macros for use by Confluence users:
projectdoc-transclusion-to-text-macro- used as a standard macroprojectdoc-transclusion-to-text-macro-curly- used in context where Confluence Wiki Markup is required
Confluence Wiki Markup
In both use cases the name of the macro projectdoc-transclusion-to-text-macro is used.
