projectdoc documents typically provide a property named 'Parent Property'. This property refers to a logical parent. This tip shows what this is all about.
Confluence allows to organize pages in a page hierarchy. Each page has a parent page, a parent page may have zero or more children. With the projectdoc Toolbox a page becomes a projectdoc document. A projectdoc document is a Confluence page with properties and sections. There are a couple of properties commonly used by all projectdoc document types. 'Commonly' indicates that there are no hard rules that a document type is required to define those properties, but the document types we define use these properties by convention.
One such property is the Parent Property. While the parent Confluence page relationship is defined by the location of two pages (one page is the child of another and this defines a hierarchy made obvious by the breadcrumbs), the parent projectdoc document relationship is a virtual one.
What does this mean and is this useful for anything?
What is the Parent Property?
The Parent Property refers to a logical parent.
This can be seen as a parent relationship with constraints. If a parent document does not meet some constraints, it is not considered a logical parent. Therefore a page with a parent page may not have a parent in the context of projectdoc.
Use cases for the Parent Property
Let's see how the Parent Property can be used.
Root Pages
A page hierarchy within a space has typically one root and this root is called the homepage. In this hierarchy there may be pages which are projectdoc documents of different types. There may be documents of type Component. There may be documents with information about systems and subsystems or services and subservices. How can we determine by a query (e.g. using the Display Table Macro) a list of all toplevel components, systems and services?
Assume that the parent relationship for a document type is defined by a filter. This filter checks the type of the parent. If it is of the same type as the child document, there is a parent relationship. If it is of a different type (or there is no parent page), then there is not. With the projectdoc Toolbox this relationship is called Parent. The tool that checks the document type is called Parent Property Macro. Template authors may use this macro to automatically establish such a relationship on document instances.
To list all root pages of documents of a given type, the Display Table Macro can be used with this query:
Different Parent Type
Some doctypes may use the Parent Property Macro differently. Suppose a document of type configuration that is designed to reference a document by a property named 'System'. This property should render a link to the parent, if this parent is actually a system document. If not the value is blank and the property will not be rendered.
Multiple Parent Types
For some document types there may be a parent of different types. Suppose the configuration document may be the child of a component, a system or a service. Since version 2.4.1 of the projectdoc Toolbox the Parent Doctype parameter of the Parent Property Macro allows to specify a list of document types that are defined as valid parents.
This way the Create from Template Macro can be used on blueprints of different document types. Once a child document is created, the property will automatically establish a link to the parent. This makes creating documents and links for navigation pretty easy.
Resources
Information on related topics.