Display Table Macro

Document Properties Marker

doctype	macro
override	false

Doctype

macro

hide

Name

Display Table Macro

Short Description

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

Parent

Parent Property

property-name	Name

Audience

Name List

doctype	role
render-no-hits-as-blank	true
render-list-as-comma-separated-values	true
names	Author, Template Author
property	Audience

Tags

Tag List


css	projectdoc-compact
names	Dynamic List, Query, Deep Link, Remote Control, Context Control, Autocomplete, Remote Controller

Type

Name List

doctype	macro-type
names	Dynamic Navigation

Iteration

value	production

hide

Supports Wiki Markup

Page Size Support

Sort Key

hide

sectionProperties

Section

index	true
show-title	false
title	Description

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.

projectdoc-box-

Note

title

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.

projectdoc-sectionbox-version

since	2.5

Wiki Markup is supported since version 2.5.

Section

title	Properties

Section

title	title	Doctype(s)

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.

Section

title	Select

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.

If no link should be generated, add '-' at the end of the property name. For properties to show a link, add a '+' at the end of the name.

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

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

projectdocprojectdoc-box-version

since	24.3

Code Block
#COLUMN_NAME{TEMPLATE_SPECIFICATION}

The column name is the label to use for the column heading. It may be replaced using 81035684.

The template specification uses placeholders to reference properties.

Example Box

title	Example Template Specification

Code Block
#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.

13

Since version 4.13 the parameter supports to reference a

Static Document Link

document	Space Properties
label	space property

. The name of the space property has to be prefixed with the paragraph sign ('§').

For instance, if the value for the select parameter is specified by the space property my-select, then the value of the select parameter is §my-select.

Transclusion

document	Display Document Properties Macro
ids	supported-html-elements

Section

title

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.

Transclusion

document	Search Tips
ids	curly-braces

Transclusion

Controlling Links

If no link should be generated, add '-' at the end of the property name. For properties to show a link, add a '+' at the end of the name.

Example Box

title	Any Column may have a Link

Short Description+, Date+

Example Box

title	Link on Short Name instead of Name

Name-, Short Name+

taget-heading-level*documentSort By PropertyidsSort By

Section

title

Max Hit

Count

The maximum number of hits requested.

Section

title	Restrict to immediate Children

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

Section

title	Counter Column

If checked adds a counter as the first column.

Since version 1.11 table cells are tagged with a CSS class named 'projectdoc-counter-column'.

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

Columns

The last character may also be a '#' in which case the property value is applied to the Count Function. The 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

Section

title	Header Translations

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

.

Section

title

Calculation Columns

Alignment

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)

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

.

projectdoc-box-

Since version 1.7.0.

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

Selector	Description
i	Integer value (Long Precision)
f	Float 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).

Transclusion

document	Number Format
ids	Content

Section

title	Exclude Self

If checked excludes this document from the query result.

example

title	Control Alignment

Name, Iteration|, Short Name+>

Section

title	Deep Links

Transclusion

document	PDAC:Deep Link
ids	Deep Links for Select Clauses

Section

title	Templates

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

Code Block
#COLUMN_NAME{TEMPLATE_SPECIFICATION}

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

Tip Box

title	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 , to replace a comma that should be used verbatim.

The template specification uses placeholders to reference properties.

Example Box

title	Example Template Specification

Code Block
#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.

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

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

Section

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

Section

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

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

Section

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

Section

title	Render Mode

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

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

Section

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

Example Box
`=mystyle` `table=mystyle` `table=mystyle[columns=20px,120px,80px]`

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

Display Table

doctype	property
select	Name, Short Description
where	$<Component>=[HTML Table]

Section

title	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

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:

ValueDescriptiondefinitionRenders 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

title	Section Render Mode

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

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.

Example Box
`1l` 1+l `1l=mystyle[columns=120px,250px]`

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

Section

title	Heading Link

If checked renders heading as link to the document.

If no heading is rendered, this flag has no effect.

Since version 1.11.

Section

title	Add Link

If specified renders the label as link to the document.

The link is rendered after the possibly extracted short description and in front of the properties table.

Since version 1.11.

Section

title	Hide Empty Row

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

Section

title	Remove Template Buttons

If checked template buttons are not transcluded.

Section

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

Section

title	Caption

The label for the table caption.

Section

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

Section

title	No Table

Deprecated Box

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.

Section

title	Suppress Headings

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

Section

title	Hide Details Link

Deprecated Box
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 the details link to the document will not be rendered in no-table mode.

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.

Version Box

since	4.13

Since version 4.13 the parameter supports to reference a

Static Document Link

document	Space Properties
label	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.

Transclusion

document	Search Tips
ids	curly-braces

Transclusion

document	Search Tips
ids	Deep Links in Where Clause

Transclusion

taget-heading-level	*
document	Sort By Property
ids	Sort By

Section

title	Max Hit Count

The maximum number of hits requested.

Section

title	Restrict to immediate Children

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

Section

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

Version Box

since	7.0

This feature is available since version 7.0 of the projectdoc Toolbox.

Section

title	Counter Column

If checked adds a counter as the first column.

Section

title	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:

Code Block
#=Counter

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

Section

title	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:

Selector	Description
i	Integer value (Long Precision)
f	Float 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).

Transclusion

document	Number Format
ids	Content

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

Section

title	Exclude Self

If checked excludes this document from the query result.

Section

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

Section

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

Section

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

Section

title	No Hits Text

Text to be rendered if no hits are shown.

This allows to customize the text message.

Section

title	Render Mode

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

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

Section

title	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 "=".

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.

Example Box
`=mystyle` `table=mystyle` `table=mystyle[columns=20px,120px,80px]`

Version Box

since	5

Since version 5 of the projectdoc Toolbox besides commas also semicolons are allowed to separate the column width.

Code Block

language	text

table=projectdoc-alternating[columns=220px;*;220px]

Since version 4.11 the columns must provide a value for the counter column (if selected).

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

Display Table

doctype	property
select	Name, Short Description
where	$<Component>=[HTML Table]

Section

title	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 text

Tip Box

title	Plain text in plain list

If the list render mode is set to plain, then the elements of the list are still rendered as specified with the Select Parameter.

In case you need to render a plain list (aka comma-separated list) then you could set the Select Parameter to Name-.

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

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:

Value	Description
`definition`	Renders 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

title	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 "+".

Version Box

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

Example Box
`*` `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").

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

Section

title	Heading Link

If checked renders heading as link to the document.

If no heading is rendered, this flag has no effect.

Since version 1.11.

Section

title	Add Link

If specified renders the label as link to the document.

The link is rendered after the possibly extracted short description and in front of the properties table.

Since version 1.11.

Section

title	Hide Empty Row

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

Section

title	Remove Template Buttons

If checked template buttons are not transcluded.

Section

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

Section

title	Caption

The label for the table caption.

Section

title	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 Section Render Mode.

Section

title	Identifier

Unique identifier for the rendered content.

This identifier is used for Remote Control and Context Controlled Macros.

Section

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

Section

title	Context controlled

When checked configures parameters via document and space properties.

For more information please refer to Context Controlled Macros.

Section

title	Remote Controls

Transclusion

document	Display List Macro
ids	Remote Controls

Section

title	No Table

Deprecated Box

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.

Section

title	Suppress Headings

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

Section

title	Hide Details Link

Deprecated Box
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 the details link to the document will not be rendered in no-table mode.

Section

title	Details

Section

title	Remote Controlled Documents

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

Example Box

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

Code Block
confluence/display/MYS/MyPage?my:doctype=code

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

Version Box

title	Updates

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

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

Section

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

Section

index	true
title	Related macros

Display Table

doctype	macro

Section

title	Details

Section

title	Remote Controlled Documents

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

Example Box

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

Code Block
confluence/display/MYS/MyPage?my:doctype=code

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

render-no-hits-as-blank	true

render-heading-as-link

hide-empty-row

remove-buttons

render-reference-box

table-caption

suppress-table-heading

Note Box
Since version 2.4 of the PDAC1 the Wiki Link Macro allows to specify parameters to call a Remote Controlled Document.

Section

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

	definition
select	Name, Short Description
sort-by	Sort Key, Name
where	Categories = "Display / Query"
exclude-self	true

Section

index	true
title	Sub-Macros

Display Table

doctype	macro
render-no-hits-as-blank	true
select	Name, Short Description
restrict-to-immediate-children	true
sort-by	Sort Key, Name

Section

title	Notes

Section

title	References

projectdoc-tour-

Section

index	true
title	Related macros

Display Table

doctype

macro

render-as-definition-
render-no-hits-as-blank	true

mode

list

definitionselectName, Short Descriptionsort-bySort Key, NamewhereCategories = "Display / Query"exclude-self

true
marker-column-property-name	Title
replace-title-with-name	true

Title	Short Description
Limitations on Query Results

true

Section

indextitle	true
title	Sub-Macros
Resources

More information on using the Display Table Macro.

projectdoc-tour-

Display Table

doctype

macro

render-no-hits-as-blank	true

selectName, Short Descriptionrestrict-to-immediate-childrentruesort-bySort Key, Name Section

title	Notes

render-as-definition-list	true
marker-column-property-name	Title
replace-title-with-name	true

Title	Short Description
Employ the Autolist Feature with Categories
From a Table to Views
Control Column Width with Display Table Macro
Compact Columns
Merging Tables and Lists
Use Display Table for Transclusion References
The hidden Section

Section

title	References

SectiontitleResources

Piwik Set Multiple Custom Variables

Name	Value
Department	projectdoc
Category	projectdoc-macro
Type	modular

Space shortcuts

Page tree

Docs

Support

Free Blueprints

Tooling for Blueprints

Free Extensions

Spaces

Plugins for Maven

Incubator

Libraries for Java

Incubator

Add-ons for Confluence

Tools

Support

Team

Legal

Versions Compared

Old Version 1

New Version Current

Key

About

Keep up-to-date!

Powered by