projectdoc Toolbox


Renders transcluded content fetched from documents of a result set.

Audience
Categories
Display / Query
Tags
Type
Since
1.5.0
Supports Wiki Markup
(tick)


List of fragments transcluded from 3 pages. Use has edit privileges, therefore the edit widget is rendered.

With the Transclude Documents Macro document authors transclude from result sets of document queries.

Since the macro requires properties to be set to select on documents, the macro transcludes only from projectdoc documents.

This feature is very convenient if used to transclude child documents, using the Transclude Documents Macro#Restrict to immediate Children parameter. Consider to use Section documents since they make it easier to define a default sort order (a feature supported by all doctypes of type Transclude Documents Macro#Subdocument).

Transcluded fragments are easily recognizable by authors (users with page edit permissions). They are surrounded by a Transclude Documents Macro#Render Reference Box that also renders widgets to quickly open the page transcluded from in edit mode (see Transclude Documents Macro#Transclude Child Documents for details).

All information is transcluded on request time. Since the macro runs a query, the list of hits is also dependent on request time and the access permissions of the user requesting the page.

Since 2.5

 

Wiki Markup is supported since version 2.5.

Properties

Doctypes

Specify the type of the documents to select. If documents from more than one document type are to be selected, enumerate them in a comma-separated list. Leave blank to select documents from any doctypes.

If a property selected from a document is not supported by a doctype, a blank cell will be rendered.

Identifiers

The identifiers of marked content or sections to include.

The identifier of a section defaults to its title.

To control the rendering you have the following options (available since version 1.8.0):

OptionDescriptionExample
-Suppress the rendering of the section title.-Description
!Suppress the section.!Description
 

Please not that complex section containment scenarios and suppressions are only supported in Confluence greater or equal to 5.8.

 

Here are some more examples on how to use identifiers to transclude sections.

IdentifiersDescription
-DescriptionRender every section, but suppress the heading of the description section.
-Description, !*Render only the description section, but without its heading.

Since version 1.17 it is possible to positively include all markers. This is necessary in case titles for selected sections need to be suppressed, but should not indicate that this is a selection.

 

Here are some more examples on how to use identifiers to transclude sections.

IdentifiersDescription
-Description, *, !ReferencesRender every section, but the references section and suppress the heading of the description section.

Tags

The tags of marked content or sections to include. Multiple elements are added in the order they appear in their document.

Select

Select properties and sections to be displayed in a table.

 

If you want to display a table above the transcluded sections you typically also want to

  • Set the name of the document as the first selected property
  • Uncheck the "Name as Heading" option

If you just want to show properties in a table, use the Display Table Macro. Refer to the Section Render Mode for details.

Where

A Lucene search expression to filter on the results. If the property contains spaces, remove them or use $[...].

Examples:

  • Name = "foo" AND ShortDescription NOT \"bar\"
  • Name = "foo" AND $[Short Description] NOT \"bar\"

Please refer to Search Tips for information on limitations and extensions on the search expression syntax provided by projectdoc.

Sort By

The comma-separated list of document property names to use for sorting.

Per default the sort key then the name of the document is used.

The last modification date is the last arbiter if all other properties are equal.

Sort Order

Add a '+' (default) for ascending, a '-' for descending order.

Sort Directives

Since 2.0

 

Since version 2.0 the sort by allows directives to control the sort order.

The directive selects the sort order breadth first (display direct children, then children at level two, the three, and so on) or depth first (run from the root node to the first leaf, second leaf, and so on until no leaf is left, then proceed with the parents sibling and so on). The sorter takes the position of the child (as specified via the space content tool to reorder pages) into account. This may be called the natural sort order since it is the sort order imposed by Confluence and it does not depend on any document property.

Note that all documents in the result set must have a common ancestor.

Directives cannot be used together with other sort constraints. A directive starts with a hashmark (#).

DirectiveDescriptionSyntax
Breadth First

A breadth first sort of a page tree.

#BREADTH_FIRST
Depth First

A depth first sort of a page tree.

#DEPTH_FIRST

There are three different implementations to choose from. Per default the Memory Implementation is used, which should be fine for almost all use cases.

ImplementationDescriptionSyntax
No MemoryThe sorter does not use additional memory to speed up sorting.#BREADTH_FIRST:no-mem
#DEPTH_FIRST:no-mem
Memory

The sorter uses additional memory to store intermediate results for reuse. This speeds up the sorting process for larger result sets.

This is the default implementation.

#BREADTH_FIRST:mem
#DEPTH_FIRST:mem
#BREADTH_FIRST

#DEPTH_FIRST

MaterializeThe sorter materializes the complete subtree and stores it for all lookups. This is typically the fastest sorter, but requires to know the root node in advance (root page ID).#BREADTH_FIRST:mat:{root page ID}
#DEPTH_FIRST:mat:{root page ID}

Artificial Properties

The projectdoc Toolbox provides a number of artificial properties, some of which may be helpful for sorting.

Property NameExample Value
Creation Date§20151008
Creation Timestamp0000001444337808000
Last Modification Date§20170429
Last Modification Date Timestamp0000001493416800000

Type Conversion

Add a type descriptor of the form

@{type/pattern}

The type is mandatory if the additional type descriptor is given. Valid values are

  • date
  • number

The pattern is optional to define a parsing pattern for the specified type.

 

Here are some examples

Sort ByThe sort order is defined by the ...
Name-... alphanumerical order of names, descending.
Calendar Week@{number}... numerical order of the calender week, ascending.
Date of Birth-@{date}... date of birth, descending.
Date of Birth@{date/dd.MM.yyyy}... date of birth, using the defined date pattern.

Max Hit Count

The maximum number of hits requested.

Restrict to immediate Children

If checked, only immediate children of the current document are valid as hits.

Exclude Self

 If checked excludes this document from the query result.

Target Heading Level

Specifies the new base level of the transcluded fragment. The top-level heading will be set to this level and subsections are transformed accordingly.

This modifier allows to render a section with subsections within another page adjusted to the target's heading level.

 

If the target heading level is set to 2 and the top-level heading is a h1, each heading within the transcluded fragment is incremented by one.

 

We are referring to the projectdoc Section Macro, not the Confluence Section Macro.

Since version 1.7 (requires Confluence 5.8+) the Target Heading Level may be set to '*'. In this case the level is calculated depending on the location of the macro. If the parent is a section at level X, the target level will be set to X+1.

 

You typically should not combine a target level of 'blank' with documents using sections (with levels or a '*').

The use of the blank target level may be deprecated in the future.

Apply Document Properties

If checked properties of the document and space are applied as placeholders.

 

This parameter is available since version 1.13.0.

Transitive Transclusion

If checked then transclusion from transcluded content is allowed.

Otherwise the transclusion macros only have access to fragments that are physically part of the document.

Since 4.0

 

The parameter is available since version 4.0.

Space Key

To limit the search on documents to the space with the given key.

The editor allows to scan for space names. If you want to select more than one space, use the space keys text field (in addition to this field).

Space Keys

To limit the search on documents to the spaces with the given keys. Use this if you want to search in several spaces.

Leave blank, if you want to search in the current space only. Use "@all" to search in all spaces.

Render no hits as blank

If the query found no hits, the result is rendered as a short text message. If a result with no hits should not be rendered at all, check this box.

No Hits Text

Text to be rendered if no hits are shown.

This allows to customize the text message.

Since 3.0

 

This parameter is supported since version 3.0.

Missing Content Message

If unchecked, no message will be rendered, if no content is to be transcluded.

Force Show

If checked then content that is hidden in its original location is shown.

This effectively overrides the hide parameter of a Section Macro or Content Marker Macro.

Since 3.0.2

 

This parameter is available since version 3.0.2 of the projectdoc Toolbox.

Prior to version 3.0 sections and content has been made visible independent of the hide configuration. Since version 3.0 the configuration of the transcluded content is strongly taken into account. This parameter again supports those use cases, where content is provided by a projectdoc document, but should not be shown in its original location.

Render Reference Box

If checked, a box that marks the transcluded text is rendered with a link to the part in the document (if the transcluded part is uniquely identifiable).

Here is an example of transcluded content from an example page named "A Document":

Example of transcluded content with box.

If you click on the name you jump to the document of the transcluded content.

A transclusion box is a handle, typically only available to users who actually have write access to a page, to quickly jump to the page from which content is transcluded.


The rendering can be controlled via space property render-transclusion-box.

The following values are valid:

only-with-edit-permission

The reference box is only rendered, if the user has edit permission. That is the user is an other and benefits from the clue of transcluded content.

never
The reference box is never rendered. This may proof useful for authors that want to check the appearance without boxes.

Remove Template Buttons

If checked template buttons are not transcluded.

This makes it easy to remove buttons from content. Otherwise the button would create new pages as children to the transcluding page.

Extract Short Description

Render the short description in front of the properties table.

Name as Heading

If checked renders the name of each transcluded document as heading.

Suppress Selection

If selected, the select is only used in suppress transclusion mode.

 

This allows authors to disable transclusion while still rendering document information to find the context.

Replacements

Specify the replacements in the macro's body.

Placeholder/replacement pairs, separated by an '=' character.

Identifier

The identifier is rendered with the encosing HTML element.

It is also useful to uniquely identify the macro in a page.

 

This parameter is available since version 1.12.0.

Identifier Classes

Apply identifier classes to render this macro as part of a group.

Since 2.3

 

This parameter is available since version 2.3 of the projectdoc Toolbox.

This identifier is used for Remote Control and Context Controlled Macros. Multiple macros on a page may have only one unique Identifier, but may share common identifier classes.

Context controlled

When checked configures parameters via document and space properties.

Since 3.1

 

Available since version 3.1 of the projectdoc Toolbox.

Details

Template Authors

Template authors may wish to reference the value of a property of the document the query is part of. Use ${...} to reference the value of a property.

  • Type = ${Name} - the type property of the documents queried is matched with the value of the name property of the document the query is part of.

Transclude Child Documents

Its fairly simple to transclude all sections of the child documents. Just check the Transclude Documents Macro#Restrict to immediate Children checkbox and set the Transclude Documents Macro#Target Heading Level to '*'. The target level will adjust the section levels of the transcluded documents to fit the level in the transcluding document.

Transclude Child Documents

 

The example shows two child documents that are transcluded. Note that the box around the transcluded content is only rendered for page authors. This allows them to jump to the transcluded document quickly.

The editor shows the checked restriction on children and the selection of the target heading level.

The screenshot of the parent document shows the transcluded child fragments rendered at level 3 under the level 2 section (arbitrarily) named 'Excerpts'.

If the user has edit privileges, an additional edit widget will be rendered to open the transcluded page in edit mode quickly.

Please note that only sections are transcluded. Therefore you have to define sections in the child documents. If you do not need to transclude all sections, use Transclude Documents Macro#Identifiers (typically the page titles) and Transclude Documents Macro#Tags to filter.

Remote Controlled Documents

 

Remote Controlled Documents are available since version 2.0 of the projectdoc Toolbox.

Remote Controlled Documents allow to control the content at request time. A HTTP request may override parameters of the transclude documents macro. A request parameter addresses a macro by its identifier. After the identifier the name of the parameter is appended, separated by a colon.

Override Parameters

 

Assume that the identifier of the transclude documents macro is set to 'my', the following call will override the doctype parameter on the page 'MyPage' in space 'MYS'.

confluence/display/MYS/MyPage?my:doctype=blank

Also the body can be overridden to replace placeholders in the transcluded fragments.

Override Body

 
body=Placeholder1%3DMyValue1\nPlaceholderX%3ValueB

The list of parameters allowed to override:

  • doctype
  • ids
  • tags
  • select
  • where
  • sort-by
  • max-hit-count
  • restrict-to-immediate-children
  • taget-heading-level (yes, the 'r' is missing!)
  • render-document-name-as-heading
  • apply-document-properties
  • space-key
  • space-keys
  • render-no-hits-as-blank
  • render-no-hits-as-blank-text
  • render-error-on-no-content
  • remove-buttons
  • extract-short-desc
  • render-heading-as-link

Since 3.1

 

Since version 3.1 these parameters can also be controlled by the context of the macro.

Related macros

Display List Macro
Lists references to projectdoc documents in a list. List contain names and optional short descriptions.
Display List Template Macro
Lists references to projectdoc documents in a list. List items are defined by templates referencing properties.
Display Table Macro
Lists references to projectdoc documents in a table. Allows to select document properties for columns. Also non-list representations are provided.
Index Card Macro
Renders transcluded content fetched from documents of a result set.
Index Entries Table Macro
Renders a table of index entries.
Random Transclusion Macro
Transcludes random content from a document marked with the content marker macro.
Tour-by-Property Macro
Renders a predefined list of documents in a table . Documents are selected by a document property. Allows to select document properties for columns. Also non-list representations are provided.
Transclusion Macro
Transcludes content from a document marked with the content marker macro.
Transclusion Reference Macro
Transcludes content via a reference from a document marked with the content marker macro.
Transclusion to Text Macro
Transcludes content from a document marked with the content marker macro and renders it as plain text.

Resources

Content Reuse
The projectdoc Toolbox provides a number of features to help teams to reuse content. Content can be transcluded individually or in form of a multitransclude. Authors can even transclude content from multiple documents in the wiki, effectively combining transclusion with automatic lists.
Transclusion
Tools to provide or consume content to support reuse.