projectdoc Toolbox

Renders a name list while taking care of special role semantics. Confluence names of groups with view permissions are added to the list of values.

The Role List Macro is in all aspects similar to the Name List Macro. The difference is that the Role List Macro also takes the names of groups with view permissions of a page into account when creating the list of roles (e.g. Audience) for a document.

Changing a Name is a Refactoring

 

Note that changing the name of a document that is referenced by the Name List Macro will not update the value in the name list.

The Name List Macro assumes that the value it contains is correct. If the referenced document changes its name, the name in the macro will not be altered and simply do not render a reference.

If users need to alter the name value, this would require a refactoring. Rename the referenced document and exchange the name in each referencing Name List Macro.

For more information on name refactorings, please refer to the article Name Refactorings.

Properties

Roles

The comma-separated list of roles to reference.

Each role name will be rendered as a link to the role document, if a document with such a name exists.

Doctype

The doctype of the documents to select.

This is usually the Role doctype, to which it defaults. But projects on the same Confluence instances may use different doctypes to document their tags. Therefore it is possible to actually specify the name of the doctype.

Sort Strategy

The sort strategy to apply to specified names. This allows to render the names provided by users to be sorted before they are rendered.

The following strategies are supported:

StrategyDescription
none

Keep the names in the order entered.

This is the default.

asc

Sort the names in ascending lexical order.

descSort the names in descending lexical order.

Since 6.1

 

This parameter is available since version 6.1.

Empty Where Clause Handling

If unchecked treat an empty where clause as match any (i.e. no constraint) or treat it as no valid match exists (in which case the displayed result is always empty).

 

You may temporarily uncheck the box to display all possible values.

Deprecated since 4.2

 

In case all properties should be shown, use the Default Strategy named all.

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 text field below in addition to this field. Only if no space is specified, the current and its delegate spaces are taken into account.

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. Only if no spaces are specified, the current and its delegate spaces are taken into account.

Render List as comma-separated Values

If checked, the list is comma-separated, otherwise the rendering produces an unordered list. If rendered with commas, the names are always shown as text. Otherwise they may be rendered as boxes.

Please refer to Box Style for details.

Restrict to one Value

If checked only one value is allowed to be selected.

The whole content is regarded as one single value and will not be split up.

Restrict to Range

If checked only values defined by the referenced doctype and constraints are allowed.

The range of valid values is defined by the doctype and the where parameter.

 

Refer to Define Status Tags for an example on how to define property value ranges.

If authors specify values not within the defined range, they are dropped.

 

If in addition to the range restriction the one-value restriction is also enforced, only the first value will be taken into account. That is: if two values are specified, where the first is not in the range, but the second is, then no value will be rendered.

Matcher

Use the matcher to filter on the name documents. Applies only if the Unique Property parameter is either the name, short name, or identifier.

In case you want to allow users to select only those values that are valid according to the matcher, check Restrict to Range. If the restriction to the range is applied, no other value can be selected.

Do not use dynamic Values as Property Values

 

Do not use any other attribute than name (Name), short name (Short Name), or identifier (Identifier) to select documents to render with this macro.

If other properties are used, the macro runs a Lucene query. If a property value is dependent on a query result, the value will not automatically be rerun if new documents are added or existing documents are altered. So the result stored with Lucene (at the time the document is saved) may not match the values rendered when the macro is shown on the page (at render time).

Lucene queries also require that all documents are present to create valid results. In case of a database rebuild this constraint is not met.

The parameter value is a constraint the documents need to match to not be filtered from the result set.

The syntax is different from those you specify in case you run a Lucene search. In queries you check the property values of the child documents.

If the property name you need to match is a alphanumeric token, you do not need to encode it (e.g. Year=2019). If it has a space, use $[...] as delimiters for the property name. For instance $[Customer Reference]. This is similar to the encoding used for Lucene queries with the Display Table Macro. You may also use ${...}  or $<...> as delimiters, but there is no reason to do so since property names should not contain special characters.

We recommend to use the square brackets ($[...]) since these are also used for Lucene queries of the property name contains a space (see Search Tips).

Values that have no spaces and are plain tokens do not need to be encoded to compare with a property property value (e.g. $[Zip Code]=45672. In case there is a space, you can use quotes as in $[Customer Reference]="123 ABC".

You may also compare the property value of the document in the result set with a property value of the document the macro is part of. Use ${...} to reference the document property by its name, for instance: $[Customer Reference]=${Default Customer Reference}

The following options are available

TypeExamplesExplanation
String Literal
  1. $[Customer Reference]="123 ABC"
  2. Reference="123 ABC"
Use string literals if the property to match with contains spaces.
Token
  1. $[Customer Reference]=123ABC
  2. Reference=123ABC
If the value does not contain spaces, no double quotes are required.
Integer Literal
  1. $[Customer Reference]=123
  2. Reference=123
For integer numbers, no double quotes are required.
Property Reference
  1. $[Customer Reference]=${Default Customer Reference}
  2. Reference=${Default Customer Reference}
For property references, no double quotes are allowed.

You may combine your property constraints by the following Boolean operators.

OperatorDescription
&AND - both properties need to match
|OR - only one of the two properties need to match
!NOT - only true if the property does not match.

Use parentheses to group your expressions.

Example Matcher Expression with !, |, and &

 
!($[Property A]="Value 1" | !$[Property B] = "Value 2") & $[Property C] = "Value 3"

Since 6.2.5

 

Since version 6.2.5 list values are allowed on both sides of a property reference expression.

$[Customer Reference]=${Default Customer Reference}

If Customer Reference and Default Customer Reference both resolve to lists of values, then each value of each set is compared. If one tuple matches, the whole expression is resolved as a match.

Currently the projectdoc Toolbox does not support lists of literals (workaround: resolve with OR connector) or comparisons with greater than or less than. Only exact matches are supported.

Property

The name of the property the values in this list are values for. This property is useful for template designers to associate the value with the name of a property.

This allows queries to reference the ancestors of a document referenced here. See Search Tips for details.

Where

A Lucene search expression to filter on the results.

This parameter only applies in case a name is provided, if the identifying property is neither the name, the short name, or the identifier of a document (in which cases the Matcher parameter is used for filtering).

If no name is provided, but the search scope is everything, the constraint specified with the Where Parameter is applied. This use case is deprecated because it requires a search to find propert values.

 

This parameter is deprecated to select on values.

See Do not use dynamic Values as Property Values for details.

For more information on queries, please refer to Search Tips.

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.

Link Properties

Removed since 3.1

 

If the Display Template Parameter is specified, name the properties here to render a link to the document the name value refers to.

If none is specified, the whole template value is considered to be the label for the link.

Skip Page Permissions

If checked, page permissions are not taken into account.

Since 3.1

 

Prior to version 3.1 this property has been called "Skip Permissions".

Skip Space Permissions

If checked, space permissions are taken into account.

Since 3.1

 

Available since version 3.1.

Identifier

Unique identifier of the macro for the rendered context.

Features may supply default configurations dependent on the value of this property.

Since 4.0

 

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

Remote Control

 

This parameter is used in the context of Remote Controlled Documents.

Identifier Classes

Identifiers to address this macro as part a group for the rendered context.

Features may supply default configurations dependent on the value of this property.

Since 4.0

 

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

Remote Control

 

This parameter is used in the context of Remote Controlled Documents.

Autocomplete Sort

Control the sort order for the autocomplete feature of this macro.

This parameter has only effect on the autocomplete feature of this macro. If empty, the default sort order is defined by the Sort Key property of the documents.

Since 4.0

 

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

Details

Box Style

Configure the Name List Macro to draws boxes around the referencing names. Per default boxes are drawn for categories and tags. This can be switched on or off by using the space property called Name List Doctype Box Style.

The default behavior is configured by the space property Name List Default Box Style.

The syntax for the space property's name is based on this naming scheme:

name-list-(doctype)-boxstyle true/false

For example use the following to disable the rendering boxes for categories:

name-list-category-boxstyle false

Change the style of the box - most commonly used to change the background color - by adding a document property to the document instance for which you want to change the style.

For instance, if you want to change the background color for the document Example of the doctype Category, add the document property CSS Style Information to the Example document (please refer to Document Properties Marker Macro for more information on document properties and how to add them to a document instance).

The value for the CSS Style Information may not only contain verbatim text. Therefore from that version on you may use macros to construct the value.

The value for the property CSS Class Information is supported to set values for the rendered HTML class attribute.

Related macros

NameShort DescriptionTags
Breadcrumb Macro
Renders a breadcrumb for the current page.
Child Documents Macro
Renders the list of child documents, matching the given filter criteria.
Display Document Properties Macro
Renders a template with property references.
Display Document Property As Image Macro
Renders the value of a document property as an image. The property value is required to an URL that points to an image.
Renders the value of a document property as a link with an alternative label.
Display Document Property As List Macro
Renders the list value of a document property.
Display Document Property Macro
Renders the value of a property of a document.
Display Document Property Ref Concat Macro
Displays a single property of a document that is referred by a property of another document and concatenates it with the value of a local property.
Display Document Property Ref Macro
Displays a document property from a referenced document.
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 Space Attribute Macro
Renders a space attribute value.
Display Space Property Macro
Renders a space property value.
Display Table Macro
Lists references to projectdoc documents in a table. Allows to select document properties for columns. Also non-list representations are provided.
Renders a locale dependent link to an external resource. The body of the macro contains the link label.
Index Card Macro
Renders transcluded content fetched from documents of a result set.
Index Entries Table Macro
Renders a table of index entries.
Name Body List Macro
Lists references to projectdoc documents. The rendering will add a link to a document, if there is a document with the given name hat is added to the body.
Name List Macro
Lists references to projectdoc documents. The rendering will add a link to a document, if there is a document with the given name.
Parent Property Macro
Renders the property of the parent document, if it has the same doctype.
Tag Body List Macro
Lists references to projectdoc documents. The rendering will add a link to a document, if there is a document with the given name hat is added to the body.
Tag List Macro
Renders a name list while taking care of special tag semantics. Confluence labels are added virtually to this list and displayed in the tags table row of the document properties table.
Tour Macro
Renders a predefined list of documents in a table.
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.
Transclusion Macro
Transcludes content from a document marked with the content marker macro.
Transclusion Reference Macro
Transcludes content via a reference from a document marked with the content marker macro.