projectdoc Toolbox

Lists references to projectdoc documents in a table. Allows to select document properties for columns. Also non-list representations are provided.

With the Display Table Macro document authors display result sets of document queries.This allows to add references to documents on the the wiki that automatically expands when new documents are added that match the given search criteria.

The macro allows to select properties and section from the documents. The search result is filtered by a where clause in Lucene syntax. The macro also allows to sort the result set by properties.

Accessing a single Property


If you only need to access a single property value within text, have a look at the Display Document Property Macro.

Since 2.5


Wiki Markup is supported since version 2.5.



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.


Specify a comma-separated list of document properties or section names to display.

If not specified, the name and short description of the document is displayed per default.

The property name may be the name of a section of the document to be transcluded.

Count Columns

The last character may also be a '#' in which case the property value is applied to the Count FunctionThe Count Function counts the number of table rows, number of list items, or number of definition terms (whichever of these three is encountered first). Otherwise the count function returns zero. This allows to render the count of a result set rendered in a section.

The Count Macro also provides this function to the contents of its body.


Column alignment can be controlled by using '<' for left, '|' for center, and '>' for right alignment. Add this character at the end of the name (even after the '+' or '#' indicator).

Control Alignment


Name, Iteration|, Short Name+>


Use Templates to render complex values in a column cell. The syntax to specify a template is


The column name is the label to use for the column heading. It may be replaced using Display Table Macro#Header Translations.

Escape Comma


A comma is considered to separate two properties to be rendered. To use a comma in your template specification you need to escape it.

Use &#44; to replace a comma that should be used verbatim.

The template specification uses placeholders to reference properties.

Example Template Specification

#My Label{${Doctype} / ${Iteration}}

The template will access the Doctype and Iteration property to render the specified string for each row in the given column.

To render a link for a property in a template, the curly braces (${...}) need to be replaced by square braces ($[...]) when referencing a document property.


#T{$[Short Description] ${Iteration}}

The example renders a link with the value of the Short Description property.


A Lucene search expression to filter on the results. If the property contains spaces, remove them or use $[...].


  • 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

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

Breadth First

A breadth first sort of a page tree.

Depth First

A depth first sort of a page tree.


There are three different implementations to choose from. Per default the Memory Implementation is used, which should be fine for almost all use cases.

No MemoryThe sorter does not use additional memory to speed up sorting.#BREADTH_FIRST:no-mem

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.



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


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

The maximum number of hits requested.

Restrict to immediate Children

If checked, only immediate children of the current document are valid as hits.

Counter Column

If checked adds a counter as the first column.

Header Translations

Comma-separated list of key value pairs. Key is the header to be replaced by the value. Format: k1=v1, k2=v2.

Use this parameter if the name of the property is not appropriate as the column header.

The default label '#' may be overridden locally like this:


The label of all number column headings is also controlled by a space property named Counter Column Header.

Calculation Columns

List column names to apply for calculation. The column names are separated by comas.

Per default the values are treated as integers. You may select the number type by the following selectors:

iInteger value (Long Precision)
fFloat value (Double Precision)

Separate the selector with a colon from the column name (e.g. Value:f).

If you require to specify the number format, add it after an equal sign (e.g. Value:f=#0.00).

Use the following symbols to define the pattern:

.Decimal Separator
#Optional Digit
,Grouping Separator


Currency Sign
%Multiply by 100 and show as percentage
Multiply by 1000 and show as per mille value
'Quote strings (to escape symbols)

Here are two examples for Locale US.

If the content is 2342.738, the pattern give these results:

¤ ##,##0.00
$ 2,342.74

Assume the following value for the next example: 0.7832


The sum is rendered in additional row. The td element is rendered with the CSS selector projectdoc-calculated-value.

Exclude Self

If checked excludes this document from the query result.

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.

Space key may reference space categories introduced by the hashmark (e.g. #myproject).

Refer to Search Space for more information on selecting spaces by their Confluence Space Category (specified via the space admin page).

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.

Render Mode

Controls how the table should render properties of the document result set.

There are three render modes: table, list, and section.

Table Render Mode

If you want to render the result in a table, leave this parameter value blank.

You may also explicitly set this value to table.

Add a CSS class by separating it with a "=".

Since version 1.5.0 setting the widths of the columns is supported. Added a columns descriptor in brackets after the CSS class name. The comma-separated list of width is passed as CSS style values for the width attribute.

  • =mystyle
  • table=mystyle
  • table=mystyle[columns=20px,120px,80px]

These CSS classes are provided by projectdoc to style your tables:

Name Short Description
Use the CSS class projectdoc-alternating for a HTML table to get alternating colored table rows.
Marks column cells that contain a row counter.
Use the CSS class projectdoc-fullwidth for a HTML table to get a table using 100% of the available width.
Use the CSS class projectdoc-halfwidth for a HTML table to get a table using 50% of the available width.
Use the CSS classprojectdoc-quarterwidth for a HTML table to get a table using 25% of the available width.
Rendered with a properties table in front of transcluded content.
Use the CSS class projectdoc-thirdwidth for a HTML table to get a table using 33% of the available width.

List Render Mode

You may render a two column result in a list. Usually this is the case for the document name and short description.

The following values are valid:

  • definition - for a definition list
  • numbered - for a numbered list
  • unnumbered - for an unnumbered list
  • plain - for a comma separated list as plain text

You may add a CSS class by separating it with a "=".

If you add a "-" at the end, the first character of the second column value (e.g. the short description) will be lower cased.

Note that there is specialized macro for rendering lists with an easier interface: Display List Macro.

The render mode parameter allows to switch between tables and lists quickly, if you started with a table, but later decide to use a more compact format for your two-column result.

Here are a few examples with valid values:

definitionRenders as a definition list.
unnumbered-Renders as an unnumbered list. The first character of the second column value is lower-cased.
definition=simpleindent-Renders a definition list with class simpleindent. The first character of the second column value is lower-cased.

Section Render Mode

To render the result with vertical tables in sections, the parameter value has to be an asterisk ('*') or an integer between 0 to 6, optionally be followed by a "+".

Since 4.5


The asterisk ('*') allows to calculate the heading level dynamically, similar to the feature provided by the Section Macro.

Otherwise there is a separate table for each document, where the first column contains the name of the property, the second its value. If the digit is zero, there will be no heading generated in front of the table. The first property in the select clause provides the value for this heading.

If a "+" sign is added (e.g. "2+"), the first property will be rendered in the heading and in the first row of the table. You may use this option to render the name as the heading and as a link in the first row of the table.

Since version 1.17 the properties table above the sections may be rendered as definition list (append an 'l'). Also the widths of the table may be controlled. For both representations a CSS class may be applied.

  • *
  • 1l
  • 1+l
  • 1=mystyle[columns=120px,250px]

Styles for definition lists provided by the projectdoc Toolbox are documented in Definition List Macro.

Since version 4.5 the short description can be extracted to be rendered in front of the table by placing the character 's' after the level (e.g. "*s").


Since version 4.5 the additional modifiers for the section render mode may appear in any order after the level is specified.

Hide Empty Row

If checked, rows in two-column tables will be hidden, if the value is blank.

Remove Template Buttons

If checked template buttons are not transcluded.

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

Since version 1.11. Prior to that version the box can only be suppressed with the space property Render Transclusion Box.


The label for the table caption.

No Table Heading

If checked no heading will be rendered.

Since version 1.17 this parameter also applies for the table above the sections in Display Table Macro#Section Render Mode.


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 Display Table Macro#Identifier, but may share common identifier classes.

Context controlled

When checked configures parameters via document and space properties.

For more information please refer to Context Controlled Macros.

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:


The tip Remote Controls for Transclusion provides a short introduction in how to use this feature.

No Table


The parameter has been removed with version 1.5.0.

Use the Transclude Documents Macro instead.

If checked, the values will be rendered as paragraphs instead of table row. Applies only to two-column tables and only makes sense if there is only one row.

Suppress Headings


The parameter has been removed with version 1.5.0, since the no-table mode has been removed in favour for the Transclude Documents Macro.

If checked, headings will not be rendered in no-table mode.


Remote Controlled Documents


Remote Controlled Documents are available since version 2.0 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'.


The list of parameters allowed to override:

  • doctype
  • select
  • where
  • sort-by
  • max-hit-count
  • restrict-to-immediate-children
  • render-counter-column
  • header-translations
  • calc-columns
  • exclude-self
  • space-key
  • space-keys
  • render-no-hits-as-blank
  • render-no-hits-as-blank-text
  • render-mode
  • render-heading-as-link
  • hide-empty-row
  • remove-buttons
  • render-reference-box
  • table-caption
  • suppress-table-heading



Since version 3.1 these parameters can also be controlled by the context of the macro.

Since version 2.4 of the projectdoc Toolbox the Wiki Link Macro allows to specify parameters to call a Remote Controlled Document.

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.

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


More information on using the Display Table Macro.

Employ the Autolist Feature with Categories
Categories, tags, and others allow to organize the pages in your wiki. First define categories pages with display table macros. Second tag your pages with these categories. With this two-step process it is easy to have multiple views to link to your information in your wiki.
From a Table to Views
Short introduction on using data tables or using views on data.
Control Column Width with Display Table Macro
The Display Table Macro provides a quick fix feature to control the width of the table columns.
Compact Columns
Tables often require a lot of space to be rendered. This tip shows how to reduce the demand of space.
Merging Tables and Lists
References listed in tables and lists may come from different sources. The Table Merger Macro allows to render a number of tables (or lists) as one table (or list).
Use Display Table for Transclusion References
It is easy to list all pages that transclude a section from the current page. This allows you, as an author, to check quickly if changes to a document that is transcluded, needs changes to the transcluding documents.
The hidden Section
The Content Marker Macro identifies content that can be displayed using the Display Table Macro. This is a short tip on how to transclude content from a projectdoc document.