- Created by Robert Reiner, last modified on 16. Aug 2023
projectdoc Toolbox
Renders the list of child documents, matching the given filter criteria.
- Audience
- Categories
- Tags
- Since
- 3.2
- Page Size Support
The macro lists child documents that meet the matcher's filter criteria.
The child documents are selected by reference and do not use a Confluence search. Therefore this macro can be used as a property value.
The use case for this macro is to be used as a property value for macros that use that value to render referenced documents.
Properties
Doctypes
The comma separated list of doctype identifiers.
Only child documents of the given doctypes are considered as match. If no doctype is specified, all doctypes are valid.
Matcher
The parameter value is a constraint the documents need to match to not be filtered from the result set.
The syntax is different from those you specify in case you run a Lucene search. In queries you check the property values of the child documents.
If the property name you need to match is a alphanumeric token, you do not need to encode it (e.g. Year=2019). If it has a space, use $[...] as delimiters for the property name. For instance $[Customer Reference]. This is similar to the encoding used for Lucene queries with the Display Table Macro. You may also use ${...} or $<...> as delimiters, but there is no reason to do so since property names should not contain special characters.
We recommend to use the square brackets ($[...]) since these are also used for Lucene queries of the property name contains a space (see Search Tips).
Values that have no spaces and are plain tokens do not need to be encoded to compare with a property property value (e.g. $[Zip Code]=45672. In case there is a space, you can use quotes as in $[Customer Reference]="123 ABC".
You may also compare the property value of the document in the result set with a property value of the document the macro is part of. Use ${...} to reference the document property by its name, for instance: $[Customer Reference]=${Default Customer Reference}
The following options are available
| Type | Examples | Explanation |
|---|---|---|
| String Literal |
| Use string literals if the property to match with contains spaces. |
| Token |
| If the value does not contain spaces, no double quotes are required. |
| Integer Literal |
| For integer numbers, no double quotes are required. |
| Property Reference |
| For property references, no double quotes are allowed. |
You may combine your property constraints by the following Boolean operators.
| Operator | Description |
|---|---|
| & | AND - both properties need to match |
| | | OR - only one of the two properties need to match |
| ! | NOT - only true if the property does not match. |
Use parentheses to group your expressions.
Example Matcher Expression with !, |, and &
!($[Property A]="Value 1" | !$[Property B] = "Value 2") & $[Property C] = "Value 3"
Since 6.2.5
Since version 6.2.5 list values are allowed on both sides of a property reference expression.
$[Customer Reference]=${Default Customer Reference}
If Customer Reference and Default Customer Reference both resolve to lists of values, then each value of each set is compared. If one tuple matches, the whole expression is resolved as a match.
Currently the projectdoc Toolbox does not support lists of literals (workaround: resolve with OR connector) or comparisons with greater than or less than. Only exact matches are supported.
Property Name
By default the name of the matching documents is rendered. The Property Name Parameter allows to select another property to be rendered for the link. It should be a unique property such as the Short Name or an Identifier.
Details
Data Center Compatibility
To support Atlassian Data Center the macro will limit the number of children displayed to the defined page size. Paging is currently not supported, therefore a warning is rendered if more than the configured maximum of hits are returned.
For more information, please refer to Limitations on Query Results.
Since 6.0
The limitation is checked since version 6.0.
Related Macros
The following macros can take advantage of the Child Documents Macro.
- Transclusion Reference Macro
- Transcludes content via a reference from a document marked with the content marker macro.
- Tour-by-Property Macro
- Renders a predefined list of documents in a table . Documents are selected by a document property. Allows to select document properties for columns. Also non-list representations are provided.
- Document Properties Supplier From Documents Macro
- Import properties from another projectdoc document.
The macro is related in function to the Parent Property Macro. While that macro creates a name reference to the parent document, the Child Documents Macro links to the child documents.
References
- Limitations on Query Results
- The number of hits for document queries is limited due to performance reasons.
