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.

Audience
Documentation Architect, Documentation Gardener, Template Author, Author
Type
Tip
Level of Experience
Expert

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.

Prerequisites

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:

  1. Aspects Property with automatic references to all aspects
  2. Import of properties of all referenced aspects
  3. Import of sections of all referenced aspects

Aspects Property

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. 

Aspect Properties

To import the supplied properties from aspects use the Aspect Properties Macro.

Aspect Sections

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.

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.

Add Aspects

To qualify as aspect the property is-a must be set to the value aspect.

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.

References

More information on the the Aspects Feature:

Aspect
An aspect is a document attached to another document to supply properties and sections. Aspects support modular documentation while the information can be still accessed in one document.
Aspects
Tools and information elated to the Aspects Feature of the projectdoc Toolbox.
Aspect References Macro
Autoconnect to aspect documents.
Aspect Properties Macro
Access properties from aspect documents.
Aspect Sections Macro
Access sections from aspect documents.

Resources

Related information to this tip:

Supply Documents
Show how to import properties from other projectdoc documents into a projectdoc document.
Child Documents Macro
Renders the list of child documents, matching the given filter criteria.
Document Properties Supplier From Documents Macro
Import properties from another projectdoc document.
Aspects light
Add a document as a child and automatically make supplied properties available in the parent.