Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Document Properties Marker
doctypemacro
overridefalse
extract-short-desctrue
(tick)
Doctypemacrohide
NameTransclude Documents Macro
Short DescriptionRenders transcluded content fetched from documents of a result set.
Parent
Parent Property
property-nameName

Audience
Name List
doctyperole
render-no-hits-as-blanktrue
render-list-as-comma-separated-valuestrue
namesAuthor, Template Author
propertyAudience

Categories
Name List
doctypecategory
namesDisplay / Query

Tags

Tag List
cssprojectdoc-compact
namesDynamic List, Query, Transclusion, Deep Link, Remote Control, Context Control, Autocomplete, Remote Controller


Type

Name List
doctypemacro-type
render-list-as-comma-separated-valuestrue
namesDynamic Navigation, Content Reuse


Iteration

Iteration
valuefinished

hide
Since1.5.0
Supports Wiki Markup(tick)
Page Size Support(tick)
Sort Keyhide
Section
indextrue
show-titlefalse
titleDescription
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
since2.5

Wiki Markup is supported since version 2.5.

Section
titleProperties
Section
titleDoctypes

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
titleIdentifiers

The identifiers of marked content or sections to include.

Content Marker
idselection-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):

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

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.

Example Box

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

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

Section
titleSelect

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
documentPDAC:Deep Link
idsDeep Links for Select Clauses


Version Box
since4.13

Since version 4.13 the parameter supports to reference a

Static Document Link
documentSpace Properties
labelspace 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
titleWhere

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

Since version 4.13 the parameter supports to reference a

Static Document Link
documentSpace Properties
labelspace 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*
documentSort By Property
idsSort By


Section
titleMax Hit Count

The maximum number of hits requested.

Section
titleRestrict to immediate Children

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

Section
titleRestrict to Favored
Transclusion
documentDisplay Table Macro
idsRestrict to Favored


Section
titleExclude Self

 If checked excludes this document from the query result.

Section
titleTarget 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
titleApply 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
titleTransitive Transclusion
Transclusion
documentTransclusion Macro
idsTransitive Transclusion


Section
titleSpace 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
titleSpace 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*
documentDisplay Table Macro
idstitleRender no hits as blank


Transclusion
taget-heading-level*
documentDisplay Table Macro
idsNo Hits Text


Section
titleMissing Content Message

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

projectdoc-transclusion-macro
taget-heading-level*
documentTransclusion Macro
idsForce Show


projectdoc-section
titleRender 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.

Transclusion
documentrender-transclusion-boxRender Transclusion Box
idsDescription


-transclusion-macrotagetheading-level
projectdoc
-
*
documentTransclusion Macro
idsIdentifier
projectdoc-section
titleRemove 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
titleExtract Short Description

Render the short description in front of the properties table.

Section
titleName as Heading

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

Section
titleHeading 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
titleAdd 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
titleSuppress 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*
documentTransclusion Macro
idsIdentifier


Transclusion
taget-heading-level*
documentDisplay Table Macro
idsIdentifier Classes


Transclusion
taget-heading-level*
documentDisplay Table Macro
idsContext controlled


Transclusion
taget-heading-level*
documentDisplay Table Macro
idsRemote 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
titlePlain 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
languagetext
product-name=projectdoc Toolbox
product-version=2.0

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

Code Block
languagetext
There current version of ${product-name} is ${product-version}.
Section
titleRich 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
titleDetails

More information to use this macro.

Section
titleTemplate 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
titleTransclude 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
titleTransclude 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
titleRemote 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
titleOverride 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
titleOverride 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
since3.1

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

projectdoc-section
indextrue
titleRelated macros

Display Table
doctypemacro
render-no-hits-as-blanktrue
render-modedefinition
selectName, Short Description
sort-bySort Key, Name
whereCategories = "Display / Query" OR $<Categories>=[Transclusion / Reference]
exclude-selftrue

...

Section
titleNotes

Section
titleReferences
Tour
render-as-definition-listtrue
replace-title-with-nametrue
TitleShort Description
Limitations on Query Results
Section
titleResources
Tour
render-as-definition-listtrue
replace-title-with-nametrue
TitleShort Description
Content Reuse
#Transclusion

...