Using Placeholders

...

Document Properties Marker

override	false

Short Description

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

Doctype

topic

hide

Name

Using Placeholders

Parent

Parent Property

property	Parent
property-name	Name

Audience

Name List

doctype	role
render-no-hits-as-blank	true
property	Audience

Level of Experience

Name List

names
doctype	experience-level
render-no-hits-as-blank	true

Advanced Beginner

Competent
property	Level of Experience
empty-as-none	false

Expected Duration

Subject

Name List

doctype	subject
property	Subject

Sponsors

Name List

doctype	stakeholder
render-no-hits-as-blank	true
property	Sponsors

Sort Key

hide

Section

show-title	false
title	Description

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.

Caution Box

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.

...

Section

title	Defining Placeholders

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

The projectdoc Toolbox supports two kinds of placeholders.

Supporting property references is in discussion for version 1

.

13:

Simple placeholders are used by

Section

title	Simple Placeholders

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

Code Block
${A simple placeholder}

Without transclusion simple placeholders are not replaced.

Note Box

Jira

server	smartics JIRA
serverId	79ad43bc-d289-364e-bfc7-46c09847bebd
key	PDAC-671

Display Properties

document	Transclusion Macro

Display Properties

document	Transclude Documents Macro

Display Properties

document	Code Block Placeholder Macro

Section

title	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 Table

render-mode	unnumbered
where	$<Categories>=[Display / Property]

...

Section

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

Section

title	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:

Code Block

language	text

product-name=projectdoc Toolbox
product-version=2.0

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

Code Block

language	text

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

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

Section

Column

Column

Currently it is not possible to replace simple placeholders with values supplied from document and space properties.

Section

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

Note Box

Jira

server	smartics JIRA
serverId	79ad43bc-d289-364e-bfc7-46c09847bebd
key	PDAC-670

is considering this approach

The Transclusion Macro and Transclude Documents Macro can be configured to also use this feature by checking Apply Document Properties.

Section

hide	true
title	Impersonator

The impersonator feature, available since version 1.13 of the projectdoc Toolbox, allows to use property references in transclusion by replacing the owning document. Usually a page is rendered in its own context. With an impersonator the page will rendered in the context of the transcluding page.

Example Box

Assume there is a page that renders the value of its property 'A' in one of its sections. If the section is transcluded by another page that impersonates the page, the value rendered will be of the impersonating page instead of the transcluded page.

Mode	Value of Property
Impersonating	Transcluding Page
Not Impersonating	Transcluded Page

The Transclusion Macro provides a property to define the impersonating page.

Note Box

Currently this feature is under development. Track it under

Jira

server	smartics JIRA
serverId	79ad43bc-d289-364e-bfc7-46c09847bebd
key	PDAC-663

.

...

Section

title	Resources

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

Tour

render-as-definition-list	true
replace-title-with-name	true

Title	Short Description
Rendering Code Fragments
Code Block Placeholder Macro
Space Properties
Using Space Properties
Document Properties
Transclusion Macro
Transclude Documents Macro
Display Table Macro
Tour Macro

Piwik Set Multiple Custom Variables

Name	Value

...

Department

projectdoc

...

Category	projectdoc-tip
Type	howto

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

Versions Compared

Old Version 2

New Version Current

Key

About

Keep up-to-date!

Powered by