Date: Fri, 29 Mar 2024 08:01:31 +0100 (CET) Message-ID: <1231156179.17789.1711695691724@09e9d69a2016> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_17788_1067044299.1711695691723" ------=_Part_17788_1067044299.1711695691723 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html
Transcludes content via a= reference from a document marked with the content marker macro.
The Transclusion Reference Macro includes content via a referen= ce property 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 conte= nt (Content Mark= er Macro).
Transclusion only works with plain Confluence pages since version 1.11 o= f 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=
=3Dreplacement
", each on its own line. Specify a placeholder like th=
is ${placeholderName}
.
The Confluence page from which to transclude content. As this field is m= andatory you have to enter the page from which to transclude content. In th= e 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 nam= e of the page to indicate that the content shall be transcluded from the pa= ge that uses this layout.
The name of a property on the referenced document that points to documen= ts to transclude from.
Since 3.1
Prior to version 3.1 of the projectdoc Toolbox the macro allowed only on= e document to be referenced.
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):
Option | Description | Example |
---|---|---|
- |
Suppress the rendering of the section title. | -Description |
! |
Suppress the section. | !Description |
Please not that complex section containment scenarios and suppressions a= re only supported in Confluence greater or equal to 5.8.
Here are some more examples on how to use identifiers to transclude sect= ions.
Identifiers | Description |
---|---|
-Description |
Render every section, but suppress the heading o= f 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. Thi= s 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 sect= ions.
Identifiers | Description |
---|---|
-Description, *, !References |
Render every section, but the references section= and suppress the heading of the description section. |
The tags of m= arked content or sections= to include. Multiple elements are added in the order they appear in th= eir document.
Specifies the new base level of the transcluded fragment. The top-leve=
l heading will be set to this level and subsections are transformed accordi=
ngly.
This modifier allows to render a section with subsections within another page adjusted to t= he target's heading level.
If the target heading level is set to 2 and the top-level heading is a h= 1, each heading within the transcluded fragment is incremented by one.
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 le= vel 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.
Tip on Heading Level Transposition
The tip Heading Level Transposition provides an example on how this feature i= s used.
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 th= e transcluded document.
See Impersonator - using Live Templates for a tip on using this featu= re.
If Apply Document Properties is checked properties of the docum= ent and space are applied as placeholders.
If Transitive Transclusion is checked then transclusion from transcluded content is allowed.<= /p>
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.
Specify a comma-separated list of page properties from the transcluded d= ocument 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
Audienc= e->Group=3DGroup 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 sig=
n ('=C2=A7
').
For instance, if the value for the select parameter is specified by the =
space property my-select
, then the value of the select paramet=
er is =C2=A7my-select
.
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.
If checked, a box that marks the transcluded text is rendered with a lin= k to the part in the document (if the transcluded part is uniquely identifi= able).
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, ty= pically only available to users who actually have write access to a page, t= o quickly jump to the page from which content is transcluded.
The rendering can be controlled vi=
a space property render-transclusion-box.
The following values are valid:
only-with-edit-permission
: The reference box is only rendered, if the user ha= s edit permission. That is the user is an other and benefits from the clue = of transcluded content.
never
: The referen=
ce box is never rendered. This may proof useful for authors that want to ch=
eck the appearance without boxes.Live Templates with Impersonator
The impersonator box has edges on the upper left and lower right corner.=
If unchecked, no message will be rendered, if no content is to be transc= luded.
Usually maintainers of the documentation site require to take notice of = missing transclusions. So if this option is checked (per default), a warnin= g message will be rendered on missing content.
If checked template bu= ttons 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.
If checked renders the name of the transcluded document as heading. Requ= ires target level to be set to a value between 1 and 6.
If checked the transcluded content represents the referenced document. U= se if Names as Heading is= not selected, but the contents represents the document.
When this option is selected, localized links pointing to a document (wi= th a link without an anchor) will target this section. Authors must only tag one transclusion to repre= sent a document per page.
Localized links are supported by the Section Macro and the Content Marker Macro.
If the transclusion renders properties of the transcluded document (see = Select), the state of this checkb= ox controls the rendering of the Short Description property. If checked the short descript= ion is rendered on top of the table showing the properties. If unchecked th= e description is rendered as a key/value property in the properties table.<= /p>
Transclusions may slow down the rendering process. To help authors to sp= eed up rendering, the space property Suppress Transclusion helps to suppress transclus= ions. This allows to render the properties table without actually transclud= ing sections from the page.
If this box is checked, the specified Select is only applied if the space is suppressing transclusions.= p>
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. Other= wise 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.=
Remote Controlled Documents are available since version 2.0 of = the projectdoc Toolbox.
Rem= ote Controlled Documents allow to control the content at request = time. A HTTP request may override parameters of the transclusion macr= o. A request parameter addresses a transclusion macro by its identifier. Af= ter the identifier the name of the parameter is appended, separated by a co= lon.
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 'M= yPage' in space 'MYS'.
conflue= nce/display/MYS/MyPage?my:document=3Db2&my:ids=3DDescription
Also the body can be overridden to replace placeholders in the transclud= ed fragments.
Override Body
body=3DPlaceholder1%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
Since 3.1
Since version 3.1 these parameters can also be controlled by the context of the ma= cro.
To search for pages that transclude information from a given document, u= se the following search syntax:
macroNa= me:projectdoc-transclusion-macro* AND ("{Title of transcluded page}")
This will return all pages that are using the transclusion macro and hav= e the title on their page content.
Using How to search for macros and macro parameters in Confluenc= e 4 would be better, but it did not work out of the box.
If you are using documentat= ion modules, the pages transcluding the module will be displayed automa= tically.
If you have a document with identical titles, it is still possible to tr=
ansclude the individual sections. Confluence ensures that each heading on a=
page is unique. This is required by the HTML 5 standard. projectdoc use th=
is service to also make sections unique. Therefore a title that occurs a se=
cond time on the same page is suffixed with '.1'
. The next wit=
h '.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 tit=
led 'Content' by selecting on 'Content.1
':
If checked renders heading as link to the document.
If no heading is rendered, this flag has no effect.
Since 4.7
Supported since version 4.7.
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.
Since 4.7
Supported since version 4.7.
Apply identifier classes to render this macro as part of a group.
This identifier is used for Remote Control and Context Controlled Macros. Multiple macro= s on a page may have only one unique Identifier, but may share common identifier classes.
Specify CSS classes to be attached to the wrapping root element of the r= endered content.
Since 4.7
Supported since version 4.7.
When checked configures parameters via document and space properties.
For more information please refer to <= a href=3D"/confluence/display/PDAC/Context+Controlled+Macros">Context Contr= olled Macros.
List of controls to pass to transcluded contexts. Controls are separated= by ampersand ('&').
Since 4.5
Available since version 4.5 of the projectdoc Toolbox.
This allows to control the rendering of remote controllable macros by se= nding controls. For more information please refer to Remote Control.
To alter the rendering of a remote control macro identified by id 'docs'= , use the following controls:
docs:se= lect=3DName,Type&docs:render-mode=3Ddefinition
The tip Remote Controls for Transclusion provides a short introduc= tion in how to use this feature.
Specify the replacements in the macro's body.
The transcluded content may specify placeholders in the form ${pla=
ceholder-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. Theref= ore only plain text replacements were supported.
Since version 4.8 the body accepts rich text. Users may specify replacem= ents in both forms.
Switch the body to preformatted and specify key/value pairs in plain tex= t form.
Here is a sample key/value list in text form.
placeho= lder-name=3DReplacement 1 Another Placeholder Name=3DReplacement Text Two
Everything before the first equal sign ('=3D
') is considere=
d to be the key for the placeholder, everthing after the equal sign up to t=
he end of the line is the value.
This is an example for placeholder replacements in the body:
product= -name=3Dprojectdoc Toolbox product-version=3D2.0
And this is an example of a fragment that defines the placeholders:
There c= urrent version of ${product-name} is ${product-version}.
To replace a placeholder with an HTML element, add a table with two colu= mns.
Only lines with table data are parsed. The table header is purely to gui= de authors and may not be specified at all.
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 con=
tent, clutter-free rendering without empty sections. Allows to transclude t=
he 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 an=
d 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.
|
|
Displays a document property from a referenced document.
|
Similar to the transclusion reference macro this macro enables to fetch inf=
ormation via a reference.
|
A list of macros supporting transclusion or embedding of contents provid= ed by Atlassian: