The Section Compiler by Reference Macro allows to mix and merge locally defined sections, by the use of the Section Macro with transcluded content from referenced documents.
The main use case for this macro is to allow to seamlessly integrate content from transcluded content as if it were a locally defined section. The order of sections is defined by a referenced property. This way users have full control over the sequence of sections.
Parameters
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.
Reference
The name of a property on the referenced document that points to documents to transclude from.
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
Please not that complex section containment scenarios and suppressions are only supported in Confluence greater or equal to 5.8.
Here are some more examples on how to use identifiers to transclude sections.
Identifiers
Description
-Description
Render every section, but suppress the heading of the description section.
-Description, !*
Render only the description section, but without its heading.
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.
Here are some more examples on how to use identifiers to transclude sections.
Identifiers
Description
-Description, *, !References
Render every section, but the references section and suppress the heading of the description section.
Tags
The tags of marked content or sections to include. Multiple elements are added in the order they appear in their document.
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.
Removed since 7.0
Since version 7.0 the transclusion from transcluded content is activated per default and cannot be deactivated.
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.
Name, Audience->Group, Audience
The table header can be replaced using the Header Translations parameter by most macros
Audience->Group=Group Name
Since 4.13
Since version 4.13 the parameter supports to reference a space property. The name of the space property has to be prefixed with the paragraph sign ('§').
For instance, if the value for the select parameter is specified by the space property my-select, then the value of the select parameter is §my-select.
Force Show
If checked then content that is hidden in its original location is shown.
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":
Example of transcluded content with box.
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 propertyrender-transclusion-box.
The following values are valid:
only-with-edit-permission
The 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.
Extract Short Description
If the transclusion renders properties of the transcluded document (see Select), the state of this checkbox controls the rendering of the Short Description property. If checked the short description is rendered on top of the table showing the properties. If unchecked the description is rendered as a key/value property in the properties table.
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.
This parameter is available since version 1.9.0.
If the macro uses placeholders, caching will automatically switched off.
Filter
List section names that should not be rendered.
User Filter Mode to choose between removing the section and hiding the section.
Since 4.8
The filter feature is available since version 4.8.
Filter Mode
The filter mode is only activated if a filter is specified.
The mode defines how filtered sections are rendered.
Mode
Description
remove
The section is not rendered. No metadata will be available on the page.
hide
The section will be rendered, but hidden from display. The metadata for this section is still available on the rendered page for further processing.
Since 4.8
The filter feature is available since version 4.8.
Heading Link
If checked renders heading as link to the document.
If no heading is rendered, this flag has no effect.
Add Link
If specified renders the label as link to the document.
The link is rendered after the possibly extracted short description and in front of the properties table.
Identifier Classes
Apply identifier classes to render this macro as part of a group.
The macro body contains the section that are referenced by the specified property. Whenever a section title matches with a specified name, the local section is rendered in the result. If it does not match a local section, then the content is transcluded. If no content is found on the referenced document, nothing is contributed to the result.
One element of the body may be Content Marker Macro with preformatted or table content. The content is passed to the transclusion services a placeholder mapping.
Example of a Placeholder Mapping with preformatted Content
Service Name=Authentication Service
Service Level=24/7
On the left side is the name of the placeholder, on the right side is the replacement text. In the example the placeholder ${Service Name} in the transcluded content will be replaced by the text Authentication Service.
The content may also be an HTML table. Each row with at least two table data elements uses the text content in the first column as key and the HTML fragment in the second column as value.
Sample table with placeholders.
Note that the table header is optional.
Since 4.8
HTML tables to define placeholder replacements is supported since version 4.8.
Renders a section, if the body is not empty. Supports authors to create content, clutter-free rendering without empty sections. Allows to transclude the content.
Renders a predefined list of documents in a table . Documents are selected by a document property. Allows to select document properties for columns. Also non-list representations are provided.
