You are viewing an old version of this page. View the current version.
Compare with Current
View Page History
« Previous
Version 33
Next »
Renders transcluded content fetched from documents of a result set.
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 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).
Transcluded fragments are easily recognizable by authors (users with page edit permissions). They are surrounded by a 115639121 that also renders widgets to quickly open the page transcluded from in edit mode (see 115639121 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.
Properties
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.
Identifiers
The identifiers of marked content or sections to include.
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 |
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.
Select
Select properties and sections to be displayed in a table.
Use Deep Link to select a property from a referenced document in the Select Clause.
The table header can be replaced using the Header Translations parameter by most macros
Audience->Group=Group Name
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.
Sort By
The comma-separated list of document property names to use for sorting.
Per default the sort key then the name of the document is used.
The last modification date is the last arbiter if all other properties are equal.
Sort Order
Add a '+' (default) for ascending, a '-' for descending order.
Sort Directives
The directive selects the sort order breadth first (display direct children, then children at level two, the three, and so on) or depth first (run from the root node to the first leaf, second leaf, and so on until no leaf is left, then proceed with the parents sibling and so on). The sorter takes the position of the child (as specified via the space content tool to reorder pages) into account. This may be called the natural sort order since it is the sort order imposed by Confluence and it does not depend on any document property.
Directives cannot be used together with other sort constraints. A directive starts with a hashmark (#).
| Directive | Description | Syntax |
|---|
| Breadth First | A breadth first sort of a page tree. | #BREADTH_FIRST |
| Depth First | A depth first sort of a page tree. | #DEPTH_FIRST |
There are three different implementations to choose from. Per default the Memory Implementation is used, which should be fine for almost all use cases.
| Implementation | Description | Syntax |
|---|
| No Memory | The sorter does not use additional memory to speed up sorting. | #BREADTH_FIRST:no-mem
#DEPTH_FIRST:no-mem |
| Memory | The sorter uses additional memory to store intermediate results for reuse. This speeds up the sorting process for larger result sets. This is the default implementation. | #BREADTH_FIRST:mem
#DEPTH_FIRST:mem
#BREADTH_FIRST
#DEPTH_FIRST
|
| Materialize | The sorter materializes the complete subtree and stores it for all look-ups. This is typically the fastest sorter, but requires to know the root node in advance (root page ID). If the page identifier is not specified, the Memory implementation is used. | #BREADTH_FIRST:mat:{root page ID}
#DEPTH_FIRST:mat:{root page ID} |
Artificial Properties
The projectdoc Toolbox provides a number of artificial properties, some of which may be helpful for sorting.
| Property Name | Example Value |
|---|
| Creation Date§ | 20151008 |
| Creation Timestamp | 0000001444337808000 |
| Last Modification Date§ | 20170429 |
| Last Modification Date Timestamp | 0000001493416800000 |
Type Conversion
Add a type descriptor of the form
The type is mandatory if the additional type descriptor is given. Valid values are
The pattern is optional to define a parsing pattern for the specified type.
Max Hit Count
The maximum number of hits requested.
Exclude Self
If checked excludes this document from the query result.
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.
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.
Apply Document Properties
If checked properties of the document and space are applied as placeholders.
Transitive Transclusion
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.
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).
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.
Render no hits as blank
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.
No Hits Text
Text to be rendered if no hits are shown.
This allows to customize the text message.
Missing Content Message
If unchecked, no message will be rendered, if no content is to be transcluded.
Force Show
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.
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.
A transclusion box is a handle, typically only available to users who actually have write access to a page, to quickly jump to the page from which content is transcluded.
The rendering can be controlled via space property render-transclusion-box.
The following values are valid:
only-with-edit-permissionThe reference box is only rendered, if the user has edit permission. That is the user is an other and benefits from the clue of transcluded content.
never- The reference box is never rendered. This may proof useful for authors that want to check the appearance without boxes.
Name as Heading
If checked renders the name of each transcluded document as heading.
Heading Link
If checked renders heading as link to the document.
If no heading is rendered, this flag has no effect.
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.
Identifier
The identifier is rendered with the encosing HTML element.
It is also useful to uniquely identify the macro in a page.
Identifier Classes
Apply identifier classes to render this macro as part of a group.
This identifier is used for Remote Control and Context Controlled Macros. Multiple macros on a page may have only one unique Identifier, but may share common identifier classes.
Remote Controls
List of controls to pass to transcluded contexts. Controls are separated by ampersand ('&').
This allows to control the rendering of remote controllable macros by sending controls. For more information please refer to Remote Control.
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.
Plain Text Replacements
Switch the body to preformatted and specify key/value pairs in plain text form.
Here is a sample key/value list in text form.
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.
Rich Text Replacements
To replace a placeholder with an HTML element, add a table with two columns.
Only lines with table data are parsed. The table header is purely to guide authors and may not be specified at all.
Details
More information to use this macro.
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.
Transclude Child Documents
Its fairly simple to transclude all sections of the child documents. Just check the 115639121 checkbox and set the 115639121 to '*'. The target level will adjust the section levels of the transcluded documents to fit the level in the transcluding document.
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 (typically the page titles) and 115639121 to filter.
Remote Controlled Documents
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.
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
