What is in the Name List?

Confluence Link

The Confluence Link is clickable since it is hard-wired to a Confluence Page. You may change the text of the label and the link still holds. Once you changed the text of the label, changes to the title of the page are no longer reflected in the label. If the label is not adjusted, the change of the page title will also change the label text.

Display Property Macros

The Display Property Macros are very similar to the Confluence Link. They are also hard-wired and point to a Confluence page. Instead of showing the page title, the macro allows to select any property (or multiple properties in form of a template) to be rendered. The user may select whether or not a link should be rendered. In case you show the name or the short name of the document, you typically want to render the link. In case you list the type property, the value is already a link to a type document and therefore no additional link is typically useful.

Display Property Macros do provide a separate label. You may either render the property value, or you don't. If you would like to change the label you should consider to use a Confluence Link.

Here is the list of macros that belong to this family:

Note that the Tour Macro and the Tour-by-Property Macro also belongs to this family. They provide static references, but list the properties of a set of documents. The Display Table Macro and the Display List Macro / Display List Template Macro also belong to this family, but are slightly different. Instead of pointing to one document statically, they point to a set of properties that match the query constraints (and are therefore also related to the Name List Macros we examine in the next section).

Name List Macros

Name List Macros are a complete different beast. The Name List Macro is often used as a property value. This is on first sight quite natural. The Name List Macro is a label wrapped inside a macro. The macro decides whether or not a link is rendered. The link is based on a query. It is not static as in case of the Confluence Link or the Display Property Macros.

Besides the name specified, the query is based on the delegate space and the doctype parameter. Per convention the tuple of name and doctype should be unique within the delegate space closure. This is not enforced. If there are multiple name/doctypes that match, the first match will be used for the link.

Therefore the contract of the Name List Macros is this: I know for sure what the text label is I want to place here. But I am unsure if there is a document on the delegate space closure that matches name and doctype. Therefore the basic behavior of the Name List Macro to a change of the name of the referenced document is not to also change the its label text. This is like a variable in a computer program. If you change the name of one variable, the names of the same variable in other lines are not automatically updated. If you want this, you need to call a refactoring operation "Rename local variable". Page authors often expect that changing the name of a document will change the label text of every Name List Macro that happen to have the old name. But this is not the case.

One beauty of this macro is its use for template authors: Template authors cannot reference document instances when designing space or page templates. But they can specify the name of a to-be-created document that is part of your design domain. And also if a space is exported. Often the type documents referenced in Name Macros are separately managed in an index space. In case the site the exported space will be imported to also has these documents, they do not need to be exported, too. In case a single document is not available on the new site then no information is lost. The property value has still the name and a link will be rendered once the missing document is created.

Currently there is also a known drawback if the Name List Macro is used as a property value. Since property values are cached for fast access, the link will not be rendered for a Name List Macro once the referenced document comes into existence. This is an issue of the projectdoc Toolbox we plan to address in one of the releases to come. Meanwhile you need to either refresh the cache using Cache Refresh Actions or to make a change to the document and publish it. This is only an issue when used as a property value. If the macro is used inside a section, the value will be updated on request time.

Note that the Name List Macros are the only dynamic macros allowed as document property values. This is because the value of the macro is static. Only the link information is dynamic. Having or not having a link makes no difference in the Lucene search. Therefore everything is cool using a Name List Macro as a property value.

Summary in Brief

So these are the characteristics of your link options: