projectdoc Toolbox

A short introduction using the impersonator feature of the projectdoc Toolbox. In this example we examine what to do to reuse a layout defined in another document.

Audience: Author, Template Author, Documentation Architect
Type: Tip
Level of Experience: Competent

Transclusion is a powerful tool for content reuse. Impersonation takes this feature of the projectdoc Toolbox for Confluence one step further an allows to render content transcluded from another document in one's own context.

Sounds complicated? Well it isn't.

Prerequisites

This feature is available for the projectdoc Toolbox for Confluence since version 2.7.

Contents

Impersonator - the Concept

What is the impersonator feature?

First: What is transclusion? The Transclusion Macro allows to reuse content from another projectdoc document. The content is referenced from the page that contains the Transclusion Macro. The content is rendered in the referenced page and the rendered content is then inserted at the location of the Transclusion Macro.

Now impersonation: The Transclusion Macro is also in use for impersonation. In this case the Impersonate parameter of the Transclusion Macro must be checked. The Transclusion Macro still references content on another page, but this time the unrendered content is delivered to the transcluding page and the this content is rendered in the context of the transcluding page. The context is typically the document properties and the document sections of the transcluding document.

That's the theory. Now let's have a look at an example!

Impersonator by Example

The impersonator feature requires two documents. One that defines the template to be reused, one uses the template and applies information from its own context.

Define the Live Template

This is what our live template for this example looks like.

The live template contains a query to select on child documents using the Display Table Macro. The template has three child documents named Sample Action 1 to Sample Action 3.
It also transcludes text from its own document body using the Transclusion Macro. An introduction is shown on the lower left. Note that the border around the text is only shown to users with write access for faster navigation.
The image on the upper right is also transcluded from a property that is part of the live template using the Display Document Property Macro.
The text on the lower right is static and is not intended to be overridden by the impersonator using the Tip Box Macro.

The structure of the projectdoc document is this:

Note that the introduction section is hidden because it is transcluded in the live template and – for this example – should only be rendered once on the page. The Section Macro and Column Macro provided by Confluence are used to define the layout.

Impersonator Document

The impersonator uses the layout defined by the live template.

The following content is from the context of the impersonator.

The child documents are the ones of the impersonator
The introduction is transcluded from the impersonator (see below)
The image is from the impersonator (see below)

The static context, the Tip of the Day is rendered as is from the live template.

So here is the context the impersonator provides.

A hidden Section Macro (the macro provided by the projectdoc Toolbox, not the macro provided by Confluence!) with the introduction text
An image as value to the Image property
The two child documents

The impersonator uses the Transclusion Macro with the impersonator feature switched on.

The macro references the live template as would be the case by a regular transclusion.

Why is it called "Live Template"?

Well, if you change the layout in the template, the impersonating documents are updated accordingly on the next request.

Changing lines and the image to the left ...

.. on next request on the impersonator, the layout is applied!

Wrap-up

You have seen an example using the impersonator feature of the projectdoc Toolbox. Impersonation is similar to transclusion, but instead of fetching a fully rendered part of a document, only the layout information is fetched as is. This layout is then rendered in the context of the transcluding page. This way the document properties and sections of the transcluding page are used for rendering. In the context of a normal transclusion the document properties and sections of the transcluded document would be used.

The impersonator is activated by checking the Impersonate parameter of the Transclusion Macro.

Impersonating – as simple as that!

References

Transclusion Macro: Transcludes content from a document marked with the content marker macro.
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.
Document Properties Marker Macro: A table containing document properties. Three columns: name, value and meta data (aka controls) to a property.
Display Table Macro: Lists references to projectdoc documents in a table. Allows to select document properties for columns. Also non-list representations are provided.
Display Document Property Macro: Renders the value of a property of a document.
Tip Box Macro: Renders a box with a tip for the reader.
projectdoc Document: projectdoc is based on projectdoc documents. Creating a projectdoc document is easy: A projectdoc document is a Confluence page using document properties and sections.
Transclusion: Tools to provide or consume content to support reuse.

Resources

Import Properties for Transclusion: Shows how to import properties from another document to be applied to placeholders in transclusions.

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