Skip to end of metadata
Go to start of metadata

Transcludes content from a document marked with the content marker macro.

Categories
Transclusion / Reference
Tags
Type
Supports Wiki Markup
(tick)

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).

 

Transclusion only works with plain Confluence pages since version 1.11 of the projectdoc Toolbox.

Before that version only transclusion from projectdoc documents was defined. Creating a projectdoc document is simple: add the Document Properties Marker Macro. No special properties required.

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.

Grafic to illustrate the @self use-case

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):

OptionDescriptionExample
-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.

IdentifiersDescription
-DescriptionRender 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.

IdentifiersDescription
-Description, *, !ReferencesRender 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.

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 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.

Tip on Heading Level Transposition

 

The tip Heading Level Transposition provides an example on how this feature is used.

Apply Document Properties

If checked properties of the document and space are applied as placeholders.

 

This parameter is available since version 1.13.0.

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.

Since 2.0

 

Use Deep Links to select a property from a referenced document in the Select Clause.

 

Name, Audience->Group, Audience

The table header can be replaced by most macros

Audience->Group=Group Name

Since 2.5

 

Please note that deep links on multiple property values are supported since version 2.5.

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":

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 property render-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.

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.

Example message on missing content 'Content2'.

Remove Template Buttons

If checked template buttons are not transcluded.

This makes it easy to remove buttons from content. Otherwise the button would create new pages as children to the transcluding page.

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.

Extract Short Description

If the transclusion renders properties of the transcluded document (see Transclusion Macro#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.

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.

 

This parameter is available since version 1.9.0.

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.

 

This parameter is available since version 1.12.0.

Replacements (Body of Macro)

Specify the replacements in the macro's body.

Placeholder/replacement pairs, separated by an '=' character of the form "placeholder=replacement", each on its own line.

Specify a placeholder like this ${placeholderName}.

 

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}.

Details

Remote Controlled Documents

 

Remote Controlled Documents are available since version 2.0 of the projectdoc Toolbox.

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.

Override Parameters

 

Assume that the identifier of the transclusion macro is set to 'my', the following call will override the document and ids parameter on the page 'MyPage' in space 'MYS'.

confluence/display/MYS/MyPage?my:document=b2&my:ids=Description

Also the body can be overridden to replace placeholders in the transcluded fragments.

Override Body

 
body=Placeholder1%3DMyValue1\nPlaceholderX%3ValueB

The list of parameters allowed to override:

  • document
  • ids
  • tags
  • select
  • taget-heading-level (yes, the 'r' is missing!)
  • render-document-name-as-heading
  • apply-document-properties
  • render-error-on-no-content
  • remove-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.

 

Using How to search for macros and macro parameters in Confluence 4 would be better, but it did not work out of the box.

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':

Related macros

Name Short Description Notes
Marks a piece of content within a document. This content can be referenced for transclusion.
Allows to mark a content with an identifier or tags.
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.
Similar to the content marker macro, but also allows to set a heading.
Renders transcluded content fetched from documents of a result set.
To transclude from documents selected by a query.
Transcludes content from a document marked with the content marker macro and renders it as plain text.
Allows to render the transcluded content as plain text. This may be further processed by other macros, such as the Body Graph Macro.
Transcludes content via a reference from a document marked with the content marker macro.
Allows to transclude from a referenced document.

Resources

Transclusion Macros

A list of macros supporting transclusion or embedding of contents provided by Atlassian:

Related Topics


Content Reuse
The projectdoc Toolbox provides a number of features to help teams to reuse content. Content can be transcluded individually or in form of a multitransclude. Authors can even transclude content from multiple documents in the wiki, effectively combining transclusion with automatic lists.
Transclusion
Tools to provide or consume content to support reuse.
Fragments Cache for Transclusions
Information on how to use the fragments cache.