projectdoc Toolbox

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

Audience
Categories
Display / Query
Tags
Type
Supports Wiki Markup
(tick)

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.

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.

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.

Sort Order

Add a '+' (default) for ascending, a '-' for descending order.

Sort Directives

Since 2.0

 

Since version 2.0 the sort by allows directives to control the sort order.

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 (#).

DirectiveDescriptionSyntax
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.

ImplementationDescriptionSyntax
No MemoryThe 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

MaterializeThe sorter materializes the complete subtree and stores it for all lookups. This is typically the fastest sorter, but requires to know the root node in advance (root page ID).#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 NameExample Value
Creation Date§20151008
Creation Timestamp0000001444337808000
Last Modification Date§20170429
Last Modification Date Timestamp0000001493416800000

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 ByThe sort order is defined by the ...
Name-... alphanumerical order of names, descending.
Calendar Week@{number}... numerical order of the calender 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.

Since 2.3

 

This parameter is available since version 2.3 of the projectdoc Toolbox.

This identifier is used for Remote Control and Context Controlled Macros. Multiple macros on a page may have only one unique Display Table Macro#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 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.

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.

Since 3.0

 

This parameter is supported since version 3.0.

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 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.