projectdoc Toolbox

Lists references to projectdoc documents in a list. List contain names and optional short descriptions.

Audience

Author, Template Author

Categories

Display / Query

Tags

Type

Dynamic Navigation

Supports Wiki Markup

Renders the query result set as a unordered, ordered or definition list.

While 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. There are parameters to tweak the visual representation easily.

Adding constraints is done via the where parameter and it is possible to sort the result.

Since 2.5

Wiki Markup is supported since version 2.5.

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.

Select for Name

Specify the property of the documents in the result set to be displayed as the list item label. The value defaults to Name if not specified.

Available since version 1.10.

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.

#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

@{type/pattern}

The type is mandatory if the additional type descriptor is given. Valid values are

date
number

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.

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 in the original result set, 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.

Remote Controls

List of controls to pass to transcluded contexts. Controls are separated by slashes ('/').

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

CSS Classes

The name of the CSS classes to apply to the list elements.

Delimiter

The delimiter between the name and the short description. Only relevant for numbered and unnumbered lists.

Render Short Description

Controls whether or not the short description should be rendered. Only relevant for numbered and unnumbered lists.

Uncapitalize Short Description

Controls whether or not the first letter of the short description should be rendered with a lower case letter.

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:

doctype
select-for-name
where
sort-by
max-hit-count
restrict-to-immediate-children
exclude-self
render-children
space-key
space-keys
list-type
css-classes
delimiter
render-short-description
uncapitalize-short-description
render-no-hits-as-blank
render-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 List Template Macro: Lists references to projectdoc documents in a list. List items are defined by templates referencing properties.
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.

Space shortcuts

Page tree

Docs

Support

Free Blueprints

Tooling for Blueprints

Free Extensions

Spaces

Plugins for Maven

Incubator

Libraries for Java