You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 4 Next »

projectdoc Toolbox

Shows how to import properties from other documents to use them for transclusion.

Type
Level of Experience

This short tip shows how properties from other documents can be used to transclude text with placeholders. Other documents will provide default values that may be overridden by the transcluding document.

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. Theses systems provide 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.

Future Development

To adapt to changes in the delegate document or the referenced document more easily, we will provide additional features in future versions of the projectdoc Toolbox.

Supplier Macros

Supplier macros add additional document properties from other sources. Currently there are two supplier macros

  1. Document Properties Supplier Macro - which adds additional properties from a HTML table within the body
  2. Document Properties Supplier Attachment Macro - which fetches properties from a Java Properties file attached to the Confluence page

Instead of fetching properties from an attached properties file, the new macro will fetch properties from a referenced document.

Impersonator

The impersonator references a single document and evaluates its contents in its own context. This way it will be very easy to reference a template with placeholders and fill in the document's properties. The impersonator will make it easier to apply properties to existing sections of the delegated document.

Resources

Content Marker Macro
Marks a piece of content within a document. This content can be referenced for transclusion.
Section Macro
Renders a section, if the body is not empty. Supports authors to create content, clutter-free rendering without empty sections. Allows to transclude the content.
Transclusion Macro
Transcludes content from a document marked with the content marker macro.
Transclusion Reference Macro
Transcludes content via a reference from a document marked with the content marker macro.
Document Properties Marker Macro
A table containing document properties. Three columns: name, value and meta data (aka controls) to a property.
Display Document Property Macro
Renders the value of a property of a document.
Display Document Property Ref Macro
Displays a document property from a referenced document.
Document Properties Supplier Macro
A table containing additional document properties. Three columns: name, value and meta data (aka controls) to a property.
Document Properties Supplier Attachment Macro
A table supplying additional document properties from an attached file.

  • No labels