Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Document Properties Marker
overridefalse


Short DescriptionShows how to import properties from other documents to use them for transclusionanother document to be applied to placeholders in transclusions.
Doctypetopichide
NameImport Properties for Transclusion
Short Name
Parent
Parent Property
property-nameName
hide
Audience

Name List
doctyperole
render-no-hits-as-blanktrue
render-list-as-comma-separated-valuestrue
namesAuthor, Template Author, Documentation Architect
propertyAudience


Subject
Name List
doctypesubject
propertySubject

Categories
Name List
doctypecategory
propertyCategories

Tags
Tag List
propertyTags

Flagshide
Iteration

Iteration
valuefilledfinished

hide
Sort Keyhide
Type

Name List
doctypetopic-type
render-no-hits-as-blanktrue
namesTip
propertyType


Level of Experience

Name List
doctypeexperience-level
render-no-hits-as-blanktrue
namesProficient
propertyLevel of Experience


Expected Duration15 min
Sponsors
Name List
doctypestakeholder
render-no-hits-as-blanktrue
propertySponsors

in-contextcorehide


...

Section
titleThe 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 These systems provide define properties that import their default values from a particular configuration document and may override properties selectively.

Section
titleConfiguration 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.


Section
titleSystem 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).

Section
titleDelegate 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:

Tip Box

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.


Section
titleReferencing 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.



...