Document Properties Marker |
---|
doctype | macro |
---|
override | false |
---|
|
Doctype | macro | hide |
---|
Name | Transclusion Macro |
|
---|
Short Description | Transcludes content from a document marked with the content marker macro. |
|
---|
Parent | |
|
---|
Audience | Name List |
---|
doctype | role |
---|
render-no-hits-as-blank | true |
---|
|
|
|
---|
Categories | Name List |
---|
doctype | category |
---|
render-no-hits-as-blank | true |
---|
names | Transclusion / Reference |
---|
|
|
|
---|
Tags | Tag List |
---|
| |
---|
css | projectdoc-compact |
---|
names | Transclusion, Remote Control, Deep Link, Context Control, Remote Controller |
---|
|
|
|
---|
Type | Name List |
---|
doctype | macro-type |
---|
names | Content Reuse |
---|
|
|
|
---|
Iteration | | hide |
---|
Supports Wiki Markup | |
|
---|
Sort Key | | hide |
---|
|
Section |
---|
index | true |
---|
show-title | false |
---|
title | Description |
---|
|
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 |
---|
document | Transclusion only from projectdoc Documents |
---|
ids | Summary |
---|
|
|
The body provides space for replacements of the form "placeholder=replacement ", each on its own line. Specify a placeholder like this ${placeholderName} . |
Section |
---|
|
Section |
---|
| 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. Transclusion |
---|
| document | Graphic to Illustrate the @self use-case
---|
ids | Summary |
---|
Section |
---|
title | Identifiers |
---|
tags | property |
---|
| 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. Transclusion |
---|
document | Transclude Documents Macro |
---|
ids | selection-options |
---|
|
|
|
Section |
---|
| The tags of marked content or sections to include. Multiple elements are added in the order they appear in their document.
|
Section |
---|
title | Target Heading Level |
---|
tags | property |
---|
| 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. Example Box |
---|
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.
Note Box |
---|
We are referring to the projectdoc Section Macro, not the Confluence Section Macro. |
|
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. projectdoc-box-version |
---|
| Since version 3.0 the blank level removes the heading of the first section, while '*' renders it. For all other sections the rendering algorithm is the same. This is because not aligning the heading levels makes no sense in most if not all use cases. | projectdoc-box-tip |
---|
title | Tip on Heading Level Transposition |
---|
| The tip Heading Level Transposition provides an example on how this feature is used. |
|
Section |
---|
title | Impersonate |
---|
tags | property |
---|
| 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. Version Box |
---|
| | This parameter is available since version 2.7. See Impersonator - using Live Templates for a tip on using this feature.
Section |
---|
title | Apply Document Properties |
---|
tags | property |
---|
| If Apply Document Properties is checked properties of the document and space are applied as placeholders. |
projectdoc- | box-version | The parameter is available since version 1.13. | projectdoc-section |
---|
title | Transitive Transclusion |
---|
tags | property |
---|
| 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.
Version Box |
---|
until | 6.x |
---|
title | Removed since 7.0 |
---|
| Since version 7.0 the transclusion from transcluded content is activated per default and cannot be deactivated. |
|
Version Box |
---|
| The parameter is available since version 4.0. |
Section |
---|
| Specify a comma-separated list of page properties from the transcluded document to be rendered in a table. You may also specify section names. Transclusion |
---|
document | PDAC:Deep Link |
---|
ids | Deep Links for Select Clauses |
---|
|
|
Version Box |
---|
| Since version 4.13 the parameter supports to reference a Static Document Link |
---|
document | Space Properties |
---|
label | 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 . |
|
Transclusion |
---|
taget-heading-level | * |
---|
document | Display Table Macro |
---|
ids | Header Translations |
---|
|
|
Section |
---|
title | Force Show |
---|
tags | property |
---|
| 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. |
projectdoc- | box-version | This parameter is available since version 3.0.2 of the projectdoc Toolbox. Prior to version 3.0 sections and content has been made visible independent of the hide configuration. Since version 3.0 the configuration of the transcluded content is strongly taken into account. This parameter again supports those use cases, where content is provided by a projectdoc document, but should not be shown in its original location. | projectdoc-section |
---|
title | Render Reference Box |
---|
tags | property |
---|
| 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. Transclusion |
---|
document | Render Transclusion Box |
---|
ids | Description |
---|
|
|
Note Box |
---|
title | Live Templates with Impersonator |
---|
| The impersonator box has edges on the upper left and lower right corner.
|
|
Section |
---|
title | Missing Content Message |
---|
tags | property |
---|
| 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.
|
Section |
---|
title | Remove Template Buttons |
---|
tags | property |
---|
| 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. |
Section |
---|
title | Name as Heading |
---|
tags | property |
---|
| If checked renders the name of the transcluded document as heading. Requires target level to be set to a value between 1 and 6. |
Section |
---|
title | Represents Document |
---|
tags | property |
---|
| 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. Version Box |
---|
| | This parameter is supported since version 3. 0.
Section |
---|
title | Extract Short Description |
---|
tags | property |
---|
| If the transclusion renders properties of the transcluded document (see 123634169 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. |
Section |
---|
title | Suppress Selection |
---|
tags | property |
---|
| 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 123634169 Select is only applied if the space is suppressing transclusions. |
Section |
---|
title | No Cache |
---|
tags | property |
---|
| 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. Note Box |
---|
This parameter is available since version 1.9.0. |
If the macro uses placeholders, caching will automatically switched off. |
Section |
---|
| The identifier is rendered with the encosing HTML element. It is also useful to uniquely identify the macro in a page. Note Box |
---|
This parameter is available since version 1.12.0. |
|
Section |
---|
| Transclusion |
---|
document | Display Table Macro |
---|
ids | Identifier Classes |
---|
|
|
|
Section |
---|
| Transclusion |
---|
document | Display Table Macro |
---|
ids | Context controlled |
---|
|
|
|
Section |
---|
| Transclusion |
---|
document | Display Table Macro |
---|
ids | Remote Controls |
---|
|
|
|
|
projectdoc-transclusion-macro |
---|
taget-heading-level | * |
---|
document | Transclude Documents Macro |
---|
ids | Macro Body |
---|
| section
title | Replacements (Body of Macro) |
---|
tags | property |
---|
|
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}
.
Example Box |
---|
This is an example for placeholder replacements in the body:
Code Block |
---|
|
product-name=projectdoc Toolbox
product-version=2.0
|
And this is an example of a fragment that defines the placeholders:
Code Block |
---|
|
There current version of ${product-name} is ${product-version}.
|
|
Section |
---|
|
Section |
---|
title | Remote Controlled Documents |
---|
| Version Box |
---|
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. Example Box |
---|
| 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'. Code Block |
---|
confluence/display/MYS/MyPage?my:document=b2&my:ids=Description |
Also the body can be overridden to replace placeholders in the transcluded fragments. Example Box |
---|
| 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
|
Section |
---|
title | Search Transcluding Pages |
---|
| To search for pages that transclude information from a given document, use the following search syntax: Code Block |
---|
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. |
Section |
---|
title | 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 ':
|
|
...