Versions Compared

Key

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

...

Document Properties Marker
overridefalse


empty

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

propertyAudience
render-list-as-comma-separated-

none

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
titlePrerequisites

This tip assumes that you are using the PDAC1 for Confluence.


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 translude 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.

Image Added

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.

Image Added

Then use the Display Document Property Ref Macro to refer to a particular property from this configuration.

Image Added

Image Added

Or override the property with a specific value.

Image Added

The way to transclude a fragment with placeholder is identical to the approach using the delegate document feature.

Image Added

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.




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

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

See

Jira
serversmartics JIRA
serverId79ad43bc-d289-364e-bfc7-46c09847bebd
keyPDAC-971
to track this issue.


Section
titleImpersonator

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.

See

Jira
serversmartics JIRA
serverId79ad43bc-d289-364e-bfc7-46c09847bebd
keyPDAC-663
to track this issue.



Section
titleSubordinate Topics
Display Table
doctypetopic
render-no-hits-as-blanktrue
render-modedefinition
selectName, Short Description
restrict-to-immediate-childrentrue
sort-bySort Key, Name

...

Section
titleResources


Tour
render-no-hits-as-blanktrue
render-as-definition-listtrue
marker-column-property-nameTitle
replace-title-with-nametrue





Piwik Set Multiple Custom Variables


NameValue
Departmentprojectdoc
Categoryprojectdoc-tip
Typehowto


...