Add a document as a child and automatically make supplied properties and sections available in the parent. A short walk-through to use the Aspect Feature in your information architecture.
This tip is an extension to the tip Supply Documents and Aspects light. In these two tips we showed briefly, how authors can have properties supplied from other projectdoc documents. The use case was in both cases a service and its configuration for IT service management with the projectdoc Toolbox for Confluence.
With this tip we go another step further: we define documents to be aspects of another document.
This tip assumes that readers are familiar with the tip Aspects light.
This tip only works with the projectdoc Toolbox version 4.0 and greater.
Create the Service Document
To prepare the service document as a receiver of aspects it needs three integration points:
- Aspects Property with automatic references to all aspects
- Import of properties of all referenced aspects
- Import of sections of all referenced aspects
The document has a property named Aspects and uses the Aspect References Macro as value.
This macro will list automatically all child documents that are flagged with the is-a property and the value aspect.
To import the supplied properties from aspects use the Aspect Properties Macro.
To import supplied sections from aspects use the Aspect Sections Macro.
We have both macros within one section. This is not a requirement. Both macros can be placed anywhere in the body of a document.
Make sure that the name of the property holding the references (Aspects) is different from the name of the section holding the other sections (Service Aspects). The name of the section can be anything, the name of the property is required to be Aspects.
View on the Service
When saved the new service document shows not much information.
Now let's add two aspects as we follow the trail of Aspects light.
To qualify as aspect the property is-a must be set to the value aspect.
In case you use a doctype that is designed to be an aspect, this property is already provided as an artificial property.
Note that properties supplied to the parent document need to be tagged with document property control supply.
The same is true for sections. To supply them the Tags parameter must be set to supply.
Add HTTP Configuration Aspect
Add the Port property – in addition to the is-a property:
Add some sections:
Note that only section 1 and 3 have been tagged with the supply keyword. Only those to sections will be exposed to the parent document.
Add Memory Configuration Aspect
Add the Required Heap Memory property — in addition to the is-a property.
Add some sections:
Again, only some of the sections are tagged with the supply keyword.
Rendered Service Document
We extract the short description, hide the Iteration property and the Subordinate Documents section. The rendered service document will look like this:
Note that the transclusion boxes are only rendered for users with write access.
More information on the the Aspects Feature:
Related information to this tip: