The name and doctype of a document also identifies a document. But not necessarily uniquely. It is good practice – that can be naturally followed most of the time – to keep the name unique for each doctype. This is not enforced, though. References to documents with names can be made with Such a link is considered to be a soft reference. The macros take the specified name and doctype literally. In case the document actually exists, a reference is rendered. If the document goes away (either by deletion, by changing the privileges, or by renaming), then name, as a string literal, is not changed. This way the document having the Name List Macro with a name as its value, is still be found by this property value (e.g. by a search or by a query conducted by a Display Table Macro). | Example Box |
|---|
This is similar to the name of a variable in a programming language. In case you change the name in a particular location, the names referring to this same variable are not automatically updated. Programmers can, however, use a refactoring tool. Such a tool allows to select the name of a variable and change all references to the variable in one step. This approach is analogous to the use of names in a Name List Macro. The "refactoring tool" for the projectdoc Toolbox, albeit not so sophisticated as the tools provided by your IDE, is the Web API. |
This of the name list as a couple of advantages. In case authors remove a doctype homepage, references to that homepage will automatically reference the homepage in a related space. In case authors import pages to another Confluence instance, the references will immediately render as links to existing documents. | Note Box |
|---|
When changing a name the reference my not be updated automatically. Either if the linked page is removed, the link may still exist, or if the page is created, the link will not be rendered. This is because the cache is not updated and the renderer fetches the stale information from the cache. It is only an issue with name list macros used as document property values. This can be fixed by refreshing the page. We are working on a solution that will automate this manual step. |
| 
