- Created by Robert Reiner, last modified on 14. May 2019
You are viewing an old version of this page. View the current version.
Compare with Current View Page History
« Previous Version 5 Next »
projectdoc Toolbox
Keeping track of transclusions using artificial properties.
- Audience
- Type
- Level of Experience
- Expected Duration
- 5 min
The projectdoc Toolbox for Confluence keeps track of transclusions between pages. The references are stored in an artificial property.
This short tip explains how this artificial property can be used to query transcluding and transcluded pages.
Transclusions
A transclusion is the act of fetching content from one Confluence page and render it in another page. The content from the page is transcluded. The page rendering the foreign content is the transcluding page. This practice supports content reuse. In its purest form the documentation consists of a vast collection of modules where each piece of information addresses only one single topic. For tutorials or other types of documents where the author addresses a complex subject, the topics are elegantly composed to form a new whole.
The projectdoc Toolbox supports transclusions by a number of macros including the Transclusion Macro (transclude one or more sections from one document) and the Transclude Documents Macro (transclude one or more sections from multiple documents). The first macro references one document explicitly, while the second macro conducts a search to find a set of documents from which the sections are transcluded. Hard references are stored in an artificial property by the name of TranscludedDocumentTitles. Searches do not create hard references since the result of the search is based on the state of the documentation at request time. When documents are added, removed, or updated, the same query may have a different result set of documents.
Listing who Transcludes
The Module doctype provides a section named Transcluded by
.
This section lists all documents that transclude contents from this module.
The Where clause reads:
$<TranscludedDocumentTitles>=[${Space Key}.${Title}]
The query selects all documents that contain the space key and title (in a special format SpaceKey.PageTitle
) in their list of pages they transclude from.
If a document A
in space ONE
transcludes content from a page B
in space ONE
and C
in space TWO
, then its artificial property TranscludedDocumentTitles
has a value of ONE.B, TWO.C
.
The query above, being part of the document C
(in space TWO
) would read like this:
$<TranscludedDocumentTitles>=[TWO.C]
So all pages that transclude from C
are part of the result set.
Listing what is transcluded
With version 3.0.3 of the projectdoc Toolbox a new artificial property named Page Key
will be provided. This page key has the form SpaceKey.PageTitle
. It allows to uniquely reference a page within a Confluence server as does the numerical page ID. While page IDs may change, for instance due to export and import of a space, the tupel space key and page title does not. The page key is controlled by the user, while the page ID is not.
With this new artificial property the following query can be specified.
$<Page Key>~(${TranscludedDocumentTitles})
It searches all pages whose page key is part of the current document's transclusion list.
Using the configuration from the last example.
The query being part of the document A
(in space ONE
) would read like this:
$<Page Key>~(ONE.B, TWO.C)
So all pages that page A
transcludes from are part of the result set.
Resources
Further information on tools and concepts mentioned in this tip.
- 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.
- Artificial Properties
- In addition to the properties specified in the document properties table, projectdoc provides additional properties drawn from Confluence or metadata.
- TranscludedDocumentTitles
- Tracks direct transclusions a document is defining.
- Page Key
- Unique reference of a page within a Confluence site.
- Module
- A documentation module is a fragment which is usually transcluded by other documents. The lifetime of a module document is independent of the lifetimes of the documents that reference it.
- Document Type
- A document type (doctype) defines the properties and section for document instances. It also provides home and index pages. In Confluence these doctypes are implemented as page blueprints, usually with one template. This template is used to create new pages in Confluence.
- No labels