projectdoc Toolbox

Renders a predefined list of documents in a table.

Audience

Author, Template Author

Categories

Display / Property

Tags

Type

Content Reuse

Renders a predefined list of documents in a table.

The contents is a table with a header line. The column headers contain the document property names to transclude. There is one column that contains the references to the documents to transclude property values from. The column is determined by the HTML anchor element. The href attribute of the anchor is used to determine the space, the label (i.e. content of the anchor element) is the title of the document.

You may add additional columns to add additional information that is rendered as specified.

Properties

This macro provides the following properties.

Counter Column

If checked adds a counter as the first column.

Replace Title with Name

If checked, the title column will be replaced with the name property value.

Use this parameter if the title is due to the uniqueness within its space requirement not the desired reference to the document.

Replace Property Name

If Replace Title with Name is selected, this property allows to substitute the Name property with any other property.

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

Render no Hits as blank

If checked and there is no value in the title column referencing a document, then the table will not be rendered.

No Hits Text

Text to be rendered if no hits are shown.

Marker Column Property Name

If specified, references to documents is only checked in this column.

Use this parameter, if you have multiple columns with references to documents. Joins are currently not supported.

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:

#=Counter

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

Child Page Reference Columns

If specified, the named columns will render references to child pages.

This is a very specific use case for this macro. Suppose you want to reference a couple of documents to be reviewed. For each document reviewers will create one additional document they add as a child to the reviewed document. This macro parameter allows to add a link to this document.

The syntax is as follows:

name=pageTitlePart?|propertyNameForLabel?|pageType?

Parameter	Description
`name`	The name of the column this rule applies to.
`pageTitlePart`	The part to the name of the page to be appended. If not given, defaults to the value of the name parameter, appended with a dash ('-') to the referenced page title.
`propertyNameForLabel`	The name of the property of the document to be used as a label.
`pageType`	Relevant for page title construction. If it is `subpage`, the name of the page containing the tour macro will be added. If it is `page`, the title is not affected.

The default rule is this:

[THE NAME IS REQUIRED]=|n/a|page

Some examples, suppose the linked page is titled "X", the page containing the macro is titled "Y":

My Column Name - A link is rendered in the column with the name 'My Column Name', if there is a page in this space called X-My Column Name.
My Column Name=-Review - A link is rendered, if there is a page in this space called X-Review.
My Column Name=-Review||subpage - A link is rendered, if there is a page in this space called X-Review - Y.

Prefer Definition List

If checked and their are only two columns, prefer rendering the value in a definition list instead of a table.

If there are not exactly two columns, the values are rendered in a table regardless of the value of this checkbox.

Style Class

The CSS class to append to the toplevel element (table or definition list).

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 ass CSS style values for the width attribute.

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

Since 5

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

mystyle[columns=20px;120px;80px]

Body

The body of the macro contains a table with table headers in the first row.

One column contains a link to the document, all other columns specify property names or templates with property names.

Since 4.5

Since version 4.5 templates are supported.

Example with Templates

To reference a property from a template use ${...} (curly brackets). In case a link should be rendered to the document containing the property use $[...] (square brackets). Any other text (like " with " or " and " in the example) is rendered verbatim.

Template Example with Document Link

#T{$[Title] / ${Iteration}}

Note that Deep Links are supported. Both forms (→ and ->) are supported.

Template Example

#SD{${Short Description} with ${Subject} and ${Ref→Tags}}

Since 6.2

Since version 6.2 the body not only allows rows with data cells for structuring, but also accepts table header cells.

Also any formatting in the identifying column is preserved. This allows add indents to create hierarchy information.

The following example shows a single separator line that takes all table columns and some arrows to mimic indenting.

The macro will (with the table heading removed) render like this:

Details

Example

The following example shows a small table that renders books with short descriptions and also adds an additional comment column.

Since version 2.4 the macro renders an error box if the body does not contain a table.

The result will add the short descriptions of the referenced books to the second column.

Template Support

A template may reference properties with ${} and $[] (the latter generating a link to the document). If there is a non-empty value in a table cell, this value is rendered.

This example shows the usage of a template in the second table row.

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.

Resources

Additional Properties: Sometimes you need to add properties to a set of documents in a given context. This can be handled in two ways: add the property to each document or use the Tour Macro.

Space shortcuts

Page tree

Docs

Support

Free Blueprints

Tooling for Blueprints

Free Extensions

Spaces

Plugins for Maven

Incubator

Libraries for Java