projectdoc Toolbox

An overview over features employing placeholders to create a modular documentation.

Parent: Tips
Level of Experience: Competent
Tags: Confluence, projectdoc, transclusion, placeholders, modular documentation, single sourcing
Type: Tip

Placeholders allow to define templates where transclusions supply context information that are inserted at render-time. This makes it possible to reuse a common form in multiple contexts. Transclusions support modular documentation and single sourcing.

There is another type placeholders used in blueprint wizards that are only applied during creation-time of a document. These placeholders are not addressed here.

For more information on this topic, please refer to Page Wizard Placeholder.

Defining Placeholders

Placeholders are defined in a document whose content is intended to be transcluded.

The projectdoc Toolbox supports two kinds of placeholders.

Simple Placeholders

A simple placeholder has a name and is delimited by a starting ${ and ends with a curly brace ('}').

${A simple placeholder}

Without transclusion simple placeholders are not replaced.

Simple placeholders are used by

Transclusion Macro - Transcludes content from a document marked with the content marker macro.
Transclude Documents Macro - Renders transcluded content fetched from documents of a result set.
Code Block Placeholder Macro - Passes a text containing placeholders to the Code Block Macro. The placeholders are replaced by the properties of a document and/or the space properties.

Property References

A property reference is a macro that displays the value of a page or space property.

Properties are defined by the Document Properties Marker Macro and the Document Properties Supplier Macro.

Property placeholders simply render the value of a property. If a property is not defined an alternative value may be rendered which is specified with the macro.

Macros used to display the property values are

Display Document Properties Macro - Renders a template with property references.
Display Document Property As Image Macro - Renders the value of a document property as an image. The property value is required to an URL that points to an image.
Display Document Property As Link Macro - Renders the value of a document property as a link with an alternative label.
Display Document Property As List Macro - Renders the list value of a document property.
Display Document Property Macro - Renders the value of a property of a document.
Display Document Property Ref Concat Macro - Displays a single property of a document that is referred by a property of another document and concatenates it with the value of a local property.
Display Document Property Ref Macro - Displays a document property from a referenced document.
Display Space Attribute Macro - Renders a space attribute value.
Display Space Property Macro - Renders a space property value.
Tour Macro - Renders a predefined list of documents in a table.

Replacing Placeholders

This is the part were a fragment from another document is transcluded and placeholders are replaced with a value.

The projectdoc Toolbox supports placeholder replacements in three different ways.

Explicit Replacement

An explicit replacements defines the replacement values with the transclusion macro.

This is an example for placeholder replacements in the body of the Transclusion Macro or the Transclude Documents Macro:

product-name=projectdoc Toolbox
product-version=2.0

And this is an example of a fragment that defines the placeholders:

There current version of ${product-name} is ${product-version}.

Here is another example with the Transclusion Macro where a letter is created using placeholders.

Context Replacement

The context replacement uses the properties defined on the page, the space the page is part of, and to spaces and pages the space or page delegates to. All properties accessible from a given point are part of the replacement context.

The Code Block Placeholder Macro uses the properties information form the page and space. The Transclusion Macro and Transclude Documents Macro can be configured to also use this feature by checking Apply Document Properties.

Resources

For more information on this and related topics, refer to the following resources.

Rendering Code Fragments: Explains the differences between and commonalities of the Confluence Code Block Macro and the projectdoc Toolbox Code Block Placeholder Macro.
Code Block Placeholder Macro: Passes a text containing placeholders to the Code Block Macro. The placeholders are replaced by the properties of a document and/or the space properties.
Space Properties: Lists the configuration options at space level.
Using Space Properties: Space properties are defined for spaces and are accessed via the Space Property Macro. This tip goes into detail in how to use space properties with inheritence and extension pages.
Document Properties: Properties are metadata that can be added to every projectdoc document. If you require a set of metadata for each instance of a document type, you should write your own doctype.
Transclusion Macro: Transcludes content from a document marked with the content marker macro.
Transclude Documents Macro: Renders transcluded content fetched from documents of a result set.
Display Table Macro: Lists references to projectdoc documents in a table. Allows to select document properties for columns. Also non-list representations are provided.
Tour Macro: Renders a predefined list of documents in a table.

Space shortcuts

Page tree

Docs

Support

Free Blueprints

Tooling for Blueprints

Free Extensions

Spaces

Plugins for Maven

Incubator

Libraries for Java

Incubator

Add-ons for Confluence

Tools

Support

Team

Legal