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.

You may link to a page that does not exist. The link is rendered like this:

If you click on the link, a new page is created. This is very close to the wiki style. Unfortunately you cannot control the blueprint to be used. Therefore this feature is of limited used.

Wiki Link Macro

The Wiki Link Macro is intended for template authors. Authors may specify these links in templates and link to pages by their title that do not yet exist. Template authors may provide the I18N key to the label since they cannot know in advance which language the context of the macro will demand.

The macro's intend is to render links, but also allows to create new pages based on a blueprint wizard, if the page it links to does not yet exist. There are a couple of configuration options to handle non-existing pages. Creating them on click is one option, render the label without link another option. You may also select the label to disappear. This may be useful in case the template author wants to add a navigation option, for instance on the space homepage, only if the target document actually exists.

The wiki link macro also allows to specify a static link. This overrides the option to search for a page. It may be used by page authors that want to redirect the link to a non-default location.

The macro also allows to specify a dynamic link by the use of the page property. The page is searched in the space closure.

The intent of this macro is to enhance navigation and to provide a tool for template authors that is context sensitive to actually render a link in a page instance or not. Having a reference to a doctype is really an afterthought to allow the creation of a new document based on a doctype. The Wiki Link Macro does not take the name or the doctype of the target document into account. It simply checks page titles in spaces, taking different space closures (delegate space and search space) into account.

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:

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). Since they are different in nature than the other options that link to a dedicated page, they are not listed in the table above.

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 List 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.

There are two variants of this macro and two specialist cousins:

Brief Summary

So these are the characteristics of your link options:

So much for some theory on working with links in Confluence and the projectdoc Toolbox.

No Link

In the editor the text looks like this:

Viewing the page shows that the Confluence Page glossary entry does not yet exist. There is no link.

Link with Tooltip

Now let's create the entry in the glossary:

Reloading the page with the link will now render a link. At the time of this request, the document for the glossary item exists.

The advantage of the Name List Macro over a Confluence Link is the rendering of the referenced document's short description as tooltip when hovering over the link.

Control the Label's Text

With version 2.3 of the projectdoc Toolbox the Name List Macro also provides a Label Parameter. In case the Name List shows only one name, the label is replacing the name. What is this good for?

Imagine that you need to change the label from Confluence Page to confluence pages:

The result is this:

The new Name List Macro makes it possible to add links to words that fit to the English sentence.

Drawbacks

Adding Confluence Links is easy since there is an auto-complete for matching page titles. When page authors use the Name List Macro, they need to know exactly the name of the document and the name of the doctype they want to refer to.

With the release of the projectdoc Toolbox version 3.3 there will be support for auto-complete for the Name List Macro and Display Document Property Macros. This release is planned to happen in autumn 2019.