
Sort Key	00002000	hide
Teaser	Image Modified	hide

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:

Panel

Excerpt Include

	Topic with Page Properties 1
	Topic with Page Properties 1
nopanel	true

This is how the transcluded content looks like:

Panel

Transclusion

document	Content to Transclude
ids	one

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 Pretend Being A to the value reader.

More Use Cases

Panel

title	Select all Content

Macro Configuration

Rendered Result

Panel

Transclusion

document	Content to Transclude

Panel

title	Select Content by ID

Macro Configuration

Rendered Result

Panel

Transclusion

document	Content to Transclude
ids	one, three

Panel

title	Select Content by Tag

Macro Configuration

Rendered Result

Panel

Transclusion

document	Content to Transclude
tags	my-tag

Panel

title	Use Sections

Macro Configuration

Rendered Result

Panel

Transclusion

document	Topic with Document Properties 1

Panel

title	Use Sections with Headers

Macro Configuration

Rendered Result

Panel

Transclusion

taget-heading-level	*
document	Topic with Document Properties 1

Panel

title	Use Sections with Header Adjustment

Macro Configuration

Rendered Result

Panel

Section

title	My Level 1 Heading

Transclusion

taget-heading-level	*
document	Topic with Document Properties 1

Note Box

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.

Panel

title	Use Placeholders

Macro Configuration

Rendered Result

Panel

Transclusion

taget-heading-level	*
document	Content With Placeholders to Transclude

Panel

title	Transclude from a Result Set

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.

Panel

title	Who transcludes?

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:

Code Block

language	text

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

Panel

title	Delegate to a Document

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.

Panel

title	Boost Performance with a Cache

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

Transclusion

document	PDAC1:Excerpt and Transclusion
ids	Summary

Macro Parameters

Here are screenshots to compare the configuration options of the two query macros visually.

The Excerpt Include Macro has very limited options, but is therefore pretty easy to use.

Section

required-permissions	write-access
title	Notes

Section

title	References

Section

title	Resources

Space shortcuts

Page tree

Versions Compared

Old Version 3

New Version Current

Key

Compare Defining Content

Compare Defining Transclusions

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

Macro Configuration

Rendered Result

Summary

Macro Parameters

Space shortcuts

Page tree

Page History

Versions Compared

Old Version 3

New Version Current

Key

Compare Defining Content

Compare Defining Transclusions

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

Macro Configuration

Rendered Result

Summary

Macro Parameters