- Created by Robert Reiner, last modified on 18. Aug 2021
You are viewing an old version of this page. View the current version.
Compare with Current View Page History
« Previous Version 31 Next »
projectdoc Toolbox
Lists references to projectdoc documents. The rendering will add a link to a document, if there is a document with the given name.
- Audience
- Categories
- Tags
- Type
Use the Name List Macro to create references to documents by name. If the document of a given document type exists with the given name, the name is rendered as a link. If the document does not exist, the name is rendered as plain text.
Note that the name of a projectdoc document may be different from its title. Please refer to Name and Title for details.
Use this macro to mark property values within a document properties table. Other than the display macros that transclude a property from another document, this macro contains the value added by the author.
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.
Properties
Names
The comma-separated list of document names to reference.
Each name will be rendered as a link to the document, if a document with such a name (and doctype, see next section) exists.
Doctype
The type of the documents to select.
The name of a document must be unique within its doctype for this macro to work property. It is not possible to reference several documents with the same name and document type.
It is allowed to specify more than one doctype. But keep in mind that the names must be unique for the set of selected doctypes.
Parent Name
If checked the name of the parent document is added in case its doctype matches with the doctypes specified by the doctype parameter. If no doctype parameter is specified, the doctype of the parent must match the doctype of the document containing the macro.
This parameter allows template authors to configure their doctype to automatically configure a property value. In case the document is added to the doctype homepage, the property value is configured by adding names manually. In case the document is added to another document, then the name of that document is automatically derived.
A typical use case is a doctype lifecycle that allows to group lifecycle phases. If the lifecycle phase is add to the doctype homepage to be selectable by multiple lifecycles, the Name List Macro behaves as usual. If the lifecycle phase is added as a child to a lifecycle document, the new phase automatically references the parent lifecycle as the lifecycle it belongs to.
Since 4.6
The parameter is available since version 4.6.
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.
Default Strategy
Select a strategy to calculate a default value in case no name is specified.
The following strategies are supported:
| Strategy | Description |
|---|---|
none | Simply keep the value empty. |
all | Render all matching names. |
ancestor | Render the first matching ancestor document's name. |
ancestor-property | Render the first ancestor's unique property value. |
New Features
This parameter is available since version 4.2 of the projectdoc Toolbox.
The strategy ancestor-property is provided since version 4.8.
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.
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.
No Create Links
When selected, overrides to disallow the rendering of names with links to create new documents.
Only relevant in case Document Creation for Name List is active.
Since 4.6
Available since version 4.6.
Where
A Lucene search expression to filter on the results.
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.
Unique Property
The name of the property to select the document. The property has to be unique and defaults to the Name property.
Display Template
Template to render instead of the plain property value.
Define property placeholders which will be replaced by the referenced property values. A property placeholder starts with ${, contains the name of the property it is a placeholder for, and ends with a curly brace.
Use templates like this to refer to properties.
The $[Name] is not ${Subject}.
The placeholders will be replaced by the values of the property Name and Subject.
The use of $[...] renders a link.
The use of Deep Links is supported.
The $[Name] is not ${Ref->Type}.
Since 4.6
Since version 4.6 there is a text version of the property that provides the list of names. This allows queries to match the document by its name although the property value is rendered by the template.
A typical use case is to render the name of persons and their organizations with a template, for instance on a minutes document. The property would be called "Attendees". For matching this document by a person (to see which minutes mention a particular person), it is inconvenient and error prone if the query would need know the pattern with the person's name and organization for the match. Therefore queries will always match by the name of the referenced property. The text form "Attendees$" can be used to match with the text rendered by the template.
When accessing the value, for instance with the Display Document Property Macro, the property "Attendees" will return the rendered HTML code snippet controlled by the template. In case the text form with the plain names needs to be accessed, use "Attendees$".
Label
In case there is only one name in this list, this label overrides the name.
If this macro is used in a section body to reference a document, e.g. a glossary item, then the label being rendered may be different from the name or any other property of the document.
In these use cases, where there is only one name, the label will be rendered instead of the property. This is similar to Confluence links, where per default the title of the referenced document is renders, but the label of the link may be an arbitrary sting.
CSS Classes
Set the Cascading Style Sheet (CSS) classes for the rendered reference.
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.
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.
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.
Logging
In case the Health Logging (de.smartics.projectdoc.atlassian.confluence.tools.health, see Logging) is activated, this macro will render issues with names not referencing a document.
The missing name is rendered together with the page coordinates (space key, title, identifier).
Related macros
| Name | Short Description | Tags |
|---|---|---|
| Breadcrumb Macro | Renders a breadcrumb for the current page. | Link |
| 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. | |
| Display Document Property As Link Macro | 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. | |
| External Link Macro | Renders a locale dependent link to an external resource. The body of the macro contains the link label. | |
| Hudson Link Macro | Render links to jobs and services on a Hudson server. | |
| Index Card Macro | Renders transcluded content fetched from documents of a result set. | |
| Index Entries Table Macro | Renders a table of index entries. | |
| Javadoc Link Macro | Links API documentation pages for Java elements. | |
| 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. | |
| Nexus Link Macro | Renders a link to an artifact stored on a Nexus server. | |
| Parent Property Macro | Renders the property of the parent document, if it has the same doctype. | |
| Role List Macro | 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. | |
| Site Link Macro | Links to a resource on a versioned site. | |
| Sonar Link Macro | Renders a link to a project on a Sonar service. | |
| Subversion Link Macro | Renders a link to a resource on a Subversion (SVN) repository. | |
| 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. | |
| Wiki Link Macro | Allows to render a link to a wiki page. |
References
- Linking to Glossary Terms
- Show how to use the Name List Macro to render links to glossary terms.
- No labels
