Transclude Documents Macro

Document Properties Marker

doctype	macro
override	false
extract-short-desc	true

Doctype

macro

hide

Name

Transclude Documents Macro

Short Description

Renders transcluded content fetched from documents of a result set.

Parent

Parent Property

property-name	Name

Audience

Name List

doctype	role
render-no-hits-as-blank	true
render-list-as-comma-separated-values	true
names	Author, Template Author
property	Audience

Tags

Tag List


css	projectdoc-compact
names	Dynamic List, Query, Transclusion, Deep Link, Remote Control, Context Control, Autocomplete, Remote Controller

Type

Name List

doctype	macro-type
render-list-as-comma-separated-values	true
names	Dynamic Navigation, Content Reuse

Iteration

value	finished

hide

Since

1.5.0

Supports Wiki Markup

Page Size Support

Sort Key

hide

Section

index	true
show-title	false
title	Description

List of fragments transcluded from 3 pages. Use has edit privileges, therefore the edit widget is rendered.

With the Transclude Documents Macro document authors transclude from result sets of document queries.

Since the macro requires properties to be set to select on documents, the macro transcludes only from projectdoc documents.

This feature is very convenient if used to transclude child documents, using the Restrict to immediate Children parameter. Consider to use Section documents since they make it easier to define a default sort order (a feature supported by all doctypes of type Subdocument).

Transcluded fragments are easily recognizable by authors (users with page edit permissions). They are surrounded by a Render Reference Box that also renders widgets to quickly open the page transcluded from in edit mode (see Transclude Child Documents for details).

All information is transcluded on request time. Since the macro runs a query, the list of hits is also dependent on request time and the access permissions of the user requesting the page.

Version Box

since	2.5

Wiki Markup is supported since version 2.5.

Section

title	Properties

Section

title	Doctypes

Specify the type of the documents to select. If documents from more than one document type are to be selected, enumerate them in a comma-separated list. Leave blank to select documents from any doctypes.

If a property selected from a document is not supported by a doctype, a blank cell will be rendered.

Section

title	Identifiers

The identifiers of marked content or sections to include.

Content Marker

id	selection-options

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`

Note Box
Please not that complex section containment scenarios and suppressions are only supported in Confluence greater or equal to 5.8.

Example Box

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.

Example Box

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.

Section

title	Tags

The tags of marked content or sections to include. Multiple elements are added in the order they appear in their document.

Section

title	Select

Select properties and sections to be displayed in a table.

Note Box

If you want to display a table above the transcluded sections you typically also want to

Set the name of the document as the first selected property
Uncheck the "Name as Heading" option

If you just want to show properties in a table, use the Display Table Macro. Refer to the Section Render Mode for details.

Transclusion

document	PDAC:Deep Link
ids	Deep Links for Select Clauses

Version Box

since	4.13

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.

Section

title	Where

A Lucene search expression to filter on the results. If the property contains spaces, remove them or use $[...].

Examples:

Name = "foo" AND ShortDescription NOT \"bar\"
Name = "foo" AND $[Short Description] NOT \"bar\"

Please refer to Search Tips for information on limitations and extensions on the search expression syntax provided by projectdoc.

projectdoc-box-version

since	4.13

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 where parameter is specified by the space property my-where, then the value of the select parameter is §my-where.

projectdoc-transclusion-macro

taget-heading-level	*
document	Sort By Property
ids	Sort By

Section

title	Max Hit Count

The maximum number of hits requested.

Section

title	Restrict to immediate Children

If checked, only immediate children of the current document are valid as hits.

Section

title	Restrict to Favored

Transclusion

document	Display Table Macro
ids	Restrict to Favored

Section

title	Exclude Self

If checked excludes this document from the query result.

Section

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

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.

Since version 1.7 (requires Confluence 5.8+) 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.

Warning Box

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.

Section

title	Apply Document Properties

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

Note Box
This parameter is available since version 1.13.0.

Section

title	Transitive Transclusion

Transclusion

document	Transclusion Macro
ids	Transitive Transclusion

Section

title	Space Key

To limit the search on documents to the space with the given key.

The editor allows to scan for space names. If you want to select more than one space, use the space keys text field (in addition to this field).

Section

title	Space Keys

To limit the search on documents to the spaces with the given keys. Use this if you want to search in several spaces.

Leave blank, if you want to search in the current space only. Use "@all" to search in all spaces.

If the query found no hits, the result is rendered as a short text message. If a result with no hits should not be rendered at all, check this box.

projectdoc-sectiontransclusion-macro

taget-heading-level	*
document	Display Table Macro
idstitle	Render no hits as blank

Transclusion

taget-heading-level	*
document	Display Table Macro
ids	No Hits Text

Section

title	Missing Content Message

If unchecked, no message will be rendered, if no content is to be transcluded.

projectdoc-transclusion-macro

taget-heading-level	*
document	Transclusion Macro
ids	Force Show

projectdoc-section

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

Transclusion

document	render-transclusion-boxRender Transclusion Box
ids	Description

-transclusion-macrotagetheading-level

projectdoc

-

*

document

Transclusion Macro

ids

Identifier

projectdoc-section

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

Section

title	Extract Short Description

Render the short description in front of the properties table.

Section

title	Name as Heading

If checked renders the name of each transcluded document as heading.

Section

title	Heading Link

If checked renders heading as link to the document.

If no heading is rendered, this flag has no effect.

Since version 1.11.

Section

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

Since version 1.11.

Section

title	Suppress Selection

If selected, the select is only used in suppress transclusion mode.

Note Box
This allows authors to disable transclusion while still rendering document information to find the context.

Transclusion

taget-heading-level	*
document	Transclusion Macro
ids	Identifier

Transclusion

taget-heading-level	*
document	Display Table Macro
ids	Identifier Classes

Transclusion

taget-heading-level	*
document	Display Table Macro
ids	Context controlled

Transclusion

taget-heading-level	*
document	Display Table Macro
ids	Remote Controls

Replacements

Section

title

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.

Section

title	Plain Text Replacements

Switch the body to preformatted and specify key/value pairs in plain text form.

Image Added

Here is a sample key/value list in text form.

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

Example Box

This is an example for placeholder replacements in the body:

Code Block

language	text

product-name=projectdoc Toolbox
product-version=2.0

And this is an example of a fragment that defines the placeholders:

Code Block

language	text

There current version of ${product-name} is ${product-version}.

Section

title	Rich Text Replacements

To replace a placeholder with an HTML element, add a table with two columns.

Image Added

Only lines with table data are parsed. The table header is purely to guide authors and may not be specified at all, separated by an '=' character.

Section

title	Details

More information to use this macro.

Section

title	Template Authors

Template authors may wish to reference the value of a property of the document the query is part of. Use ${...} to reference the value of a property.

Type = ${Name} - the type property of the documents queried is matched with the value of the name property of the document the query is part of.

Section

title	Transclude Child Documents

Its fairly simple to transclude all sections of the child documents. Just check the Restrict to immediate Children checkbox and set the Target Heading Level to '*'. The target level will adjust the section levels of the transcluded documents to fit the level in the transcluding document.

Example Box

title	Transclude Child Documents

The example shows two child documents that are transcluded. Note that the box around the transcluded content is only rendered for page authors. This allows them to jump to the transcluded document quickly.

The editor shows the checked restriction on children and the selection of the target heading level.

The screenshot of the parent document shows the transcluded child fragments rendered at level 3 under the level 2 section (arbitrarily) named 'Excerpts'.

If the user has edit privileges, an additional edit widget will be rendered to open the transcluded page in edit mode quickly.

Please note that only sections are transcluded. Therefore you have to define sections in the child documents. If you do not need to transclude all sections, use Identifiers (typically the page titles) and Tags to filter.

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 transclude documents macro. A request parameter addresses a macro by its identifier. After the identifier the name of the parameter is appended, separated by a colon.

Example Box

title	Override Parameters

Assume that the identifier of the transclude documents macro is set to 'my', the following call will override the doctype parameter on the page 'MyPage' in space 'MYS'.

Code Block
confluence/display/MYS/MyPage?my:doctype=blank

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

Example Box

title	Override Body

body=Placeholder1%3DMyValue1\nPlaceholderX%3ValueB

The list of parameters allowed to override:

doctype
ids
tags
select
where
sort-by
max-hit-count
restrict-to-immediate-children
taget-heading-level (yes, the 'r' is missing!)
render-document-name-as-heading
apply-document-properties
space-key
space-keys
render-no-hits-as-blank
render-no-hits-as-blank-text
render-error-on-no-content
remove-buttons
extract-short-desc
render-heading-as-link

projectdoc-box-version

since	3.1

Since version 3.1 these parameters can also be controlled by the context of the macro.

projectdoc-section

index	true
title	Related macros

Display Table

doctype	macro
render-no-hits-as-blank	true
render-mode	definition
select	Name, Short Description
sort-by	Sort Key, Name
where	Categories = "Display / Query" OR $<Categories>=[Transclusion / Reference]
exclude-self	true

...

Section

title	Notes

Section

title	References

Tour

render-as-definition-list	true
replace-title-with-name	true

Title	Short Description
Limitations on Query Results

Section

title	Resources

Tour

render-as-definition-list	true
replace-title-with-name	true

Title	Short Description
Content Reuse
#Transclusion

...

Space shortcuts

Page tree

Docs

Support

Free Blueprints

Tooling for Blueprints

Free Extensions

Spaces

Plugins for Maven

Incubator

Libraries for Java

Incubator

Add-ons for Confluence

Tools

Support

Team

Legal

Versions Compared

Old Version 14

New Version Current

Key

About

Keep up-to-date!

Powered by