- Created by Robert Reiner, last modified on 05. Jan 2024
projectdoc Toolbox
Lists references to projectdoc documents in a list. List items are defined by templates referencing properties.
- Audience
- Categories
- Tags
- Type
- Since
- 1.17
- Supports Wiki Markup
- Page Size Support
Renders the query result set as a unordered, ordered or definition list. The list items are rendered according to templates.
The Display Table Macro allows to select the properties to be displayed in columns of a table, the Display List Macro renders the name of the document and optionally its short description.
Adding constraints is done via the where parameter and it is possible to sort the result.
Properties
The macro provides the following properties.
Doctype
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.
Name Template
Define a template to render list item values or definition list terms.
To reference a property, use this syntax: ${Property Name}
Link references are supported: Replace the curly braces with brackets: $[Property Name]. If no link reference is provided, the whole name is rendered as link.
Since 4.13
Since version 4.13 the parameter supports to reference a space property. The name of the space property has to be prefixed with the paragraph sign ('§').
For instance, if the value for the name template parameter is specified by the space property my-name-template, then the value of the name template parameter is §my-name-template.
Since 5.0
Since version 5.0.6 the parameter supports a selection of HTML tags to structure the template.
Supported inline elements
bbrcitecodedddtemili
qsmallspanstrikestrongsubsupu
Supported block elements
blockquotedlolppreul
Data Template
Define a template to render definition list descriptions. This parameter is only considered if a list of type definition is used.
To reference a property, use this syntax: ${Property Name}
Link references are supported: Replace the curly braces with brackets: $[Property Name].
Since 4.13
Since version 4.13 the parameter supports to reference a space property. The name of the space property has to be prefixed with the paragraph sign ('§').
For instance, if the value for the data template parameter is specified by the space property my-data-template, then the value of the data template parameter is §my-data-template.
Since 5.0
Since version 5.0.6 the parameter supports a selection of HTML tags to structure the template.
Supported inline elements
bbrcitecodedddtemili
qsmallspanstrikestrongsubsupu
Supported block elements
blockquotedlolppreul
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.
Since 4.13
Since version 4.13 the parameter supports to reference a 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.
Curly Braces
Curly braces may cause problems on some instances of Confluence when used in a string parameter field of a macro. This is especially true (and reproducible) if you use an opening and an immediate closing bracket like this: "{}".
This is a known issue (CONFSERVER-33399) and is also discussed in Do curly braces in string macro parameters break the macro?
To work around this problem you may escape the curly braces with a backslash as in
$[Story Points] = $\{Magic Value\}
You need to use this workaround if you cannot save the page (as described in the issue above). Otherwise it is just a failed rendering of the macro in the macro editor.
This issue is solved since version 5.0.
Since version 2.0 of the projectdoc Toolbox Deep Links are supported for property references (on the right side) as an experimental features.
$<Story Points> = [${Master->Ref Story Points}]Note that you cannot use deep links on the left side of the where clause without Materialization. Since version 4.5 this is supported by property control mat, by space property Materialize by Doctype, or by Doctype Descriptor. Materialization is also possible in prior versions of the projectdoc Toolbox with a little more verbose approach. Read Materialize Properties for more information on this.
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.
Since 4.13
Since version 4.13 the parameter supports to reference a space property. The name of the space property has to be prefixed with the paragraph sign ('§').
For instance, if the value for the sort parameter is specified by the space property my-sort-by, then the value of the select parameter is §my-sort-by.
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.
Note that all documents in the result set must have a common ancestor.
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. |
|
| 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 ( 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
@{type/pattern}
The type is mandatory if the additional type descriptor is given. Valid values are
datenumber
The pattern is optional to define a parsing pattern for the specified type.
Here are some examples
| Sort By | The sort order is defined by the ... |
|---|---|
Name- | ... alphanumerical order of names, descending. |
Calendar Week@{number} | ... numerical order of the calendar week, ascending. |
Date of Birth-@{date} | ... date of birth, descending. |
Date of Birth@{date/dd.MM.yyyy} | ... date of birth, using the defined date pattern. |
Max Hit Count
Limit the maximum number of hits in the result set.
Restrict to immediate Children
If checked, only immediate children of the current document are valid as hits.
Restrict to Favored
If checked, only documents marked with a star are valid hits.
This feature allows to filter documents in the result set that are not marked as favored.
Pages that are marked with are star a currently defined as "Saved for Later" and where previously deemed as favorite (or favourite).
Since 7.0
This feature is available since version 7.0 of the projectdoc Toolbox.
Exclude Self
If checked excludes this document from the query result.
Render Children
For each hit also render the direct and transitive children.
Does not apply to definition lists.
It is not necessary for the children to match the query constraints. If a child is also a hit, it will be rendered twice. Limit the chance of redundant hit by selecting the restriction to immediate children or by adjusting the query accordingly.
If you just want to select on the root documents of a type, use the following in your where clause:
*:* -Parent:[* TO *]
This feature is available since version 1.10.
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.
List Type
Controls the type of the list. May be an ordered, unordered or definition list.
Identifier
Unique identifier for the rendered content.
This identifier is used for Remote Control and Context Controlled Macros.
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.
Context controlled
When checked configures parameters via document and space properties.
3.2
Available since version 3.2 of the projectdoc Toolbox.
The tip Use Context Controlled Macros provides a short introduction in how to use this feature.
Remote Controls
List of controls to pass to transcluded contexts. Controls are separated by ampersand ('&').
Since 4.5
Available since version 4.5 of the projectdoc Toolbox.
This allows to control the rendering of remote controllable macros by sending controls. For more information please refer to Remote Control.
To alter the rendering of a remote control macro identified by id 'docs', use the following controls:
docs:select=Name,Type&docs:render-mode=definition
The tip Remote Controls for Transclusion provides a short introduction in how to use this feature.
CSS Classes
The name of the CSS classes to apply to the list elements.
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.
Details
Remote Controlled Documents
Remote Controlled Documents for this marco are available since version 3.2 of the projectdoc Toolbox.
Remote Controlled Documents allow to control the content at request time. A HTTP request may override parameters of the macro. A request parameter addresses a macro by its identifier. After the identifier the name of the parameter is appended, separated by a colon.
Override Parameters
Assume that the identifier of the macro is set to 'my', the following call will override the doctype parameter on the page 'MyPage' in space 'MYS'.
confluence/display/MYS/MyPage?my:doctype=code
The list of parameters allowed to override:
doctypeproperties-display-template-nameproperties-display-template-datawheresort-bymax-hit-countrestrict-to-immediate-childrenexclude-selfrender-childrenspace-keyspace-keyslist-typecss-classesrender-no-hits-as-blankrender-no-hits-as-blank-text
Related macros
- Display List Macro
- Lists references to projectdoc documents in a list. List contain names and optional short descriptions.
- Display Table Macro
- Lists references to projectdoc documents in a table. Allows to select document properties for columns. Also non-list representations are provided.
- Index Card Macro
- Renders transcluded content fetched from documents of a result set.
- Index Entries Table Macro
- Renders a table of index entries.
- 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.
- Transclude Documents Macro
- Renders transcluded content fetched from documents of a result set.
References
- Limitations on Query Results
- The number of hits for document queries is limited due to performance reasons.
