Shows how to import properties from another document to be applied to placeholders in transclusions.
The Use Case
Imagine there is a document type Configuration to define configurations for systems. A configuration document defines configuration options for a set of systems.
A second doctype defines Systems. These systems define properties that import their default values from a particular configuration document and may override properties selectively.
Configuration Doctype
For simplicity the Configuration doctype defines two properties and a text with variables, we call placeholders.
There is a text with placeholders referencing the values from these properties.
Note that this section is hidden.
To actually render the section where the two placeholders are replaced with actual property values, a transclusion is required.
The following parameters of the Transclusion Macro are set.
First reference the current document by the @self reference (this is especially important for template authors).
Second it is also important to define the section to transclude (otherwise there will be a recursion detected with an error box).
Last but not least you need to check the box for Apply Document Properties to actually use the document's properties for the placeholders.
So this is essentially the document as seen by the document authors.
Note that the box around the contents of the Description section is only visible to users of Confluence with write access to the document. It is a marker to remind authors that the content is transcluded. Also note that you may hide the properties since the information is presented in the Description section.
System Doctype
The System doctype now needs to override the Port property with a specific value (81), but will use the default memory from the configuration.
There are two way to import the values from the Web Server Configuration. Either by Delegate Document or by the use of Display Document Property macros (e.g. Display Document Property Ref Macro).
Delegate Document
With a delegate document you import properties and sections selectively. First use the Document Properties Marker Macro to define the delegate document.
Specify the properties you need to import with the delegate control.
Then transclude the section Configuration Description with the placeholders from the Web Server Configuration:
If you need to transclude the Configuration Description section directly, you need to create an area for your transcluded contents using the Content Marker Macro and set this macro to 'hide'. All sections within this area are not hidden individually.
This is a special handling used for delegation documents. Transclusion macros do not check the hide parameter of the elements they transclude.
The drawback of this approach is that you need to add every property you add to the configuration document, also to all system documents that delegate to this configuration.
You can use the Web API Extension to add properties to a selection of documents.
Referencing Documents
Instead of delegating to a single document you may reference a number of documents by using properties. The following example references a single configuration, but you can easily reference different configurations for different aspects, like security or resources.
Then use the Display Document Property Ref Macro to refer to a particular property from this configuration.
Or override the property with a specific value.
The way to transclude a fragment with placeholder is identical to the approach using the delegate document feature.
This approach again has the drawback that it does not adopt to changes to the configuration document. Again, the Web API Extension may make it easier to add the properties to a selection of documents, but this is quite cumbersome.
