Compare the excerpt feature of Confluence with the transclusion feature of the projectdoc Toolbox.
Compare Defining Content
The content for this show case is defined in Topic with Page Properties 1.
Here is the screenshot with the Excerpt Macro:
The definition is quite simple: a container marking the text that can be transcluded. There can be only one excerpt per page. If there are more than one, the Excerpt Include Macro automatically selects the first marked content on the page.
The content for this show case is defined in Content to Transclude.
Here is the screenshot with the Content Marker Macro:
The definition is also quite simple. The container encloses the content to make it ready for transclusion. But with the transclusion feature of the projectdoc Toolbox you may have multiple content marked for transclusion.
The configuration options for the macro are simple to use.
The marked content can be hidden. So this content is for reuse only. For this show case we do not need to configure anything.
There are more configuration options for this macro.
We add an identifier and one tag, just as an example. This is how you can define which content is to be transcluded.
Compare Defining Transclusions
To transclude from a page, define the page to transclude from.
Since there is no choice in what part of the page to transclude, you are done.
To transclude from a page use the page and the identifier of the content.
If you would not specify the identifier, every content prepared for transclusion would be transcluded.
This is how the transcluded content looks like:
A description one.
This is how the transcluded content looks like:
It is easy to jump to the page of the content in editor mode.
Simply click the button "Go to Included Page".
It is easy to jump to the page of the content in view mode.
Simply click on the page title to open the page in view mode. If you click on the edit icon, the page will be opened in the editor in another browser tab.
This way it is easy for page authors to recognize which content is transcluded. If you have no page edit privileges, you will not see the blue transclusion box. If you are an author and you do not want the box to be rendered, either unckeck the "Render Reference Box" from the Transclusion Macro or (preferred) set the space property called Pretend Being A to the value reader.
More Use Cases
Macro Configuration
Rendered Result
Macro Configuration
Rendered Result
Macro Configuration
Rendered Result
Macro Configuration
Rendered Result
Macro Configuration
Rendered Result
Macro Configuration
Rendered Result
Yes, the configuration of the macro is the same as in the last example. The difference in this use case is the location of the Transclusion Macro. It is inside a section with a heading at level one. The content from the other page is also at level one. We therefore set the target level to the asterisk ('*'), asking projectdoc to calculate the level for the transcluded content 'auto-magically'.
This works for Confluence version 5.8 and up. If you use a previous version, you cannot use the asterisk, but you can use this feature by explicitly defining the target level. The asterisk default to level 1.
Macro Configuration
Rendered Result
Content 73 .
You may specify a query on documents with the Transclude Documents Macro and transclude from the documents in the result set.
This feature is helpful if you want to show content from a number of documents that match you query criteria.
It is quiet easy to use the Display Table Macro to list all pages that transclude from the given page.
Use the following query criteria in the Where parameter of the macro:
$<TranscludedDocumentTitles>=[${Space Key}.${Name}]
Have a look at Artificial Properties for more information on what metadata is automatically provided by projectdoc for every document. You may also want to glance over the Search Tips.
The Document Properties Marker Macro provides the Delegate Document parameter to transclude document properties and document sections of another document.
This feature is handy if you want to add information to another document, usually of the same document type, and add some small changes. Since the content is transcluded, the delegating document always shows the current information provided by the delegate document.
If you have a very large number of transclusions you might want to enable the transclusion fragment cache.
This cache is disabled by default since small installations usually do not need the cache. Caching might result in stale information if not used properly. That is if a transcluded content is dynamic (for instance if you use the Display Table Macro), a cached content is not updated. Authors therefore have to determine if on the basis of the macro if it is safe to use the cache or not.
To not burden users facing no performance problems with the task of employing the macro correctly, the fragment cache is currently switched off per default.
Summary
Macro Parameters
Here are screenshots to compare the configuration options of the two query macros visually.
