- Created by Robert Reiner, last modified on 13. Jul 2020
projectdoc Toolbox
Controls how document instances are located in a space.
- ID
projectdoc.links.doctype-instances-localization-mode- Data Type
- enumeration
- Default Value
heuristic- Value Range
heuristic,search,children-check- Since
- 4.1
The space property controls how the projectdoc Toolbox is checking for document instances.
The service that checks for document instances is used by the Wiki Link Macro. The macro renders the link label to a doctype homepage in a different format dependent on whether there a documents of the given type or not. This makes it easier for users visiting the homepage of a space to determine which of the referenced doctype homepages actually have documents as their children.
The property recognizes three values that enforce different strategies to determine a result.
| Search mode | Semantics | Pros | Cons |
|---|---|---|---|
heuristic(default) | Space | Quick, no search required | No reliable results based on naming conventions |
search | Space | Reliable results | Search executed which drains performance when rendering a page with plenty of links |
children-check (recommended) | Homepage | Reliable results | Page traversal required with additional checks which drains performance when rendering a page with plenty of links |
Space semantics check for document instances in the whole space, while homepage semantics only check for document instances as children of the homepage.
In case you need reliable results, we recommend the children-check mode. If your use case is that users visiting the homepage should not click on a link pointing to a doctype homepage without documents, then this is your choice. In case your semantics allow a document instance to be anywhere in a space, use the search mode and check for performance issues. In case your main concern is performance, stick with the default value heuristic.
Details
Heuristic Mode
The heuristic mode is based on naming conventions of internationalization (I18N) keys. This is the default search mode.
The mode is based on a few quick and fast lookups. But the heuristic mode is not reliable. In case there is an index page, the heuristic assumes that there are document instances of the given type. This may not be true.
I18N keys are specified in resource bundles, typically in a properties file, that is deployed as an app (formally known as plugin or add-on) to a Confluence server.
The homepage for a given doctype needs to have a I18N key of the following format:
<any-chars>.content.<doctype>.home.title
The index page for doctypes is assumed to be referenced by the following I18N key:
<any-chars>.content.<doctype>.index.all.title
<any-chars> may actually contain any chars that are valid for an I18N key. <doctype> is a placeholder to represent the identifier of a doctype.
In case all documents are removed, the index page needs to be removed manually.
Requirement Doctype Example
A key used by the Requirement doctype.
projectdoc.content.requirement.home.title projectdoc.content.requirement.index.all.title
Imaginary Fancy Report Doctype
A key for the imaginary Fancy Report doctype of a sample organisation.
com.example.myorg.content.fancy-report.home.title com.example.myorg.content.fancy-report.index.all.title
In order to not clash with keys from projectdoc products, users should use their own key prefixes. These could be defined by the name of their internet domain.
Search
A reliable way to determine if there are documents of a given type in a given space is to execute a search. If the search result is empty, there are none. The drawback is that there is an additional search for each link on a page.
The doctype is derived from the I18N key.
Since 4.5
Since version 4.5 the calculation of the doctype checks for the Flags property of the doctype homepage.
projectdoc.doctype-home, projectdoc.all, projectdoc.related.doctype.<doctype>
Children Check
The children check iterates over the children of a the referenced homepage and checks if at least one of them is of the desired doctype.
The doctype is derived from the I18N key.
Since 4.5
Since version 4.5 the calculation of the doctype checks for the Flags property of the doctype homepage.
projectdoc.doctype-home, projectdoc.all, projectdoc.related.doctype.<doctype>
Resources
- Wiki Link Macro
- Allows to render a link to a wiki page.
