| 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 | |
|
|---|
| Audience | | Name List |
|---|
| doctype | role |
|---|
| render-no-hits-as-blank | true |
|---|
| render-list-as-comma-separated-values | true |
|---|
| names | Author, Template Author |
|---|
| property | Audience |
|---|
|
|
|
|---|
| Categories | | Name List |
|---|
| doctype | category |
|---|
| names | Display / Query |
|---|
|
|
|
|---|
| 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 | | hide |
|---|
| Since | 1.5.0 |
|
|---|
| Supports Wiki Markup | |  |
|
|---|
| Page Size Support | |  |
|
|---|
| Sort Key | | hide |
|---|
|
| Section |
|---|
| index | true |
|---|
| show-title | false |
|---|
| title | Description |
|---|
|
 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 115639121 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 115639121 Subdocument). Transcluded fragments are easily recognizable by authors (users with page edit permissions). They are surrounded by a 115639121 Render Reference Box that also renders widgets to quickly open the page transcluded from in edit mode (see 115639121 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.
|
| Section |
|---|
|
| Section |
|---|
| 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 |
|---|
| The identifiers of marked content or sections to include. | Content Marker |
|---|
| 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 |
|---|
| The tags of marked content or sections to include. Multiple elements are added in the order they appear in their document. |
| Section |
|---|
| 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 |
|---|
|
|
| section | title | Where | | 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. |
|
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. | | Transclusion |
|---|
| taget-heading-level | * |
|---|
| document | Sort By Property |
|---|
| ids | Sort By |
|---|
| | Section |
|---|
| 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 |
|---|
| 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.
Image Removed
| 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 |
|---|
|
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 |
|---|
|
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. |
| Transclusion |
|---|
| taget-heading-level | * |
|---|
| document | Display Table Macro |
|---|
| ids | 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. |
| Transclusion |
|---|
| taget-heading-level | * |
|---|
| document | Transclusion Macro |
|---|
| ids | Force Show |
|---|
|
| 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":
Image Removed
If you click on the name you jump to the document of the transcluded content.
| Transclusion |
|---|
| document | Render Transclusion Box |
|---|
| ids | Description |
|---|
|
| 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 |
|---|
|
If checked renders the name of each transcluded document as heading. |
| Section |
|---|
|
If checked renders heading as link to the document. If no heading is rendered, this flag has no effect. Since version 1.11. |
| Section |
|---|
|
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 |
|---|
|
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. |
| Section |
|---|
|
Specify the replacements in the macro's body. Placeholder/replacement pairs, separated by an '=' character. |
| 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 |
|---|
|
|
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. | 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 where parameter is specified by the space property my-where, then the value of the select parameter is §my-where. |
|
| Transclusion |
|---|
| taget-heading-level | * |
|---|
| document | Sort By Property |
|---|
| ids | Sort By |
|---|
|
|
| Section |
|---|
|
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 |
|---|
|
| Transclusion |
|---|
| document | Display Table Macro |
|---|
| ids | Restrict to Favored |
|---|
|
|
|
| Section |
|---|
|
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. Image Added | 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 |
|---|
|
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 |
|---|
|
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. |
| Transclusion |
|---|
| taget-heading-level | * |
|---|
| document | Display Table Macro |
|---|
| ids | 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. |
| Transclusion |
|---|
| taget-heading-level | * |
|---|
| document | Transclusion Macro |
|---|
| ids | Force Show |
|---|
|
|
| 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": Image Added If you click on the name you jump to the document of the transcluded content. | Transclusion |
|---|
| document | Render Transclusion Box |
|---|
| ids | Description |
|---|
|
|
|
| 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 |
|---|
|
If checked renders the name of each transcluded document as heading. |
| Section |
|---|
|
If checked renders heading as link to the document. If no heading is rendered, this flag has no effect. |
| Section |
|---|
|
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. |
| Section |
|---|
|
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 |
|---|
|
|
| Section |
|---|
|
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 AddedHere 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 |
|---|
| 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 |
|---|
| 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. |
|
| Section |
|---|
|
More information to use this macro. |
| Section |
|---|
| title | Details| Section |
|---|
| 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 115639121 Restrict to immediate Children checkbox and set the 115639121 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 115639121 Identifiers (typically the page titles) and 115639121 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 |
|---|
| 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 |
|---|
| body=Placeholder1%3DMyValue1\nPlaceholderX%3ValueB |
|
The list of parameters allowed to override: doctypeidstagsselectwheresort-bymax-hit-countrestrict-to-immediate-childrentaget-heading-level (yes, the 'r' is missing!)render-document-name-as-headingapply-document-propertiesspace-keyspace-keysrender-no-hits-as-blankrender-no-hits-as-blank-text
render-error-on-no-contentremove-buttonsextract-short-descrender-heading-as-link
|
|
|---|
...
| Section |
|---|
|
| Tour |
|---|
| render-as-definition-list | true |
|---|
| replace-title-with-name | true |
|---|
| |
|
| Section |
|---|
|
| Tour |
|---|
| render-as-definition-list | true |
|---|
| replace-title-with-name | true |
|---|
| |
|
...
