Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Document Properties Marker
doctypemacro
overridefalse
extract-short-desctrue


Doctypemacrohide
NameTransclude Documents Macro
Short DescriptionRenders transcluded content fetched from documents of a result set.
Parent
Parent Property
property-nameName

Audience
Name List
doctyperole
render-no-hits-as-blanktrue
render-list-as-comma-separated-valuestrue
namesAuthor, Template Author
propertyAudience

Categories
Name List
doctypecategory
namesDisplay / Query

Tags

Tag List
cssprojectdoc-compact
namesDynamic List, Query, Transclusion, Deep Link, Remote Control


Type

Name List
doctypemacro-type
render-list-as-comma-separated-valuestrue
namesDynamic Navigation, Content Reuse


Iteration

Iteration
valuefinished

hide
Since1.5.0
Supports Wiki Syntax(tick)
Sort Keyhide



Section
indextrue
show-titlefalse
titleDescription
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 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 81035635).

Transcluded fragments are easily recognizable by authors (users with page edit permissions). They are surrounded by a reference box that also renders widgets to quickly open the page transcluded from in edit mode (see 81035635 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.

Version Box
since2.5

Wiki syntax is supported since version 2.5.



Section
titleProperties


Section
titleDoctypes

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.


Section
titleIdentifiers

The identifiers of marked content or sections to include.

Content Marker
idselection-options

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


Note Box

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


Example Box

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.

Example Box

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.





Section
titleTags

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


Section
titleSelect

Select properties and sections to be displayed in a table.

Note Box

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.



Section
titleWhere

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.


Transclusion
taget-heading-level*
documentSort By Property
idsSort By


Section
titleMax Hit Count

The maximum number of hits requested.


Section
titleRestrict to immediate Children

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


Section
titleExclude Self

 If checked excludes this document from the query result.


Section
titleTarget 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.

Example Box

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.

Note Box

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.

Warning Box

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.



Section
titleApply Document Properties

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

Note Box

This parameter is available since version 1.13.0.



Section
titleSpace 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).


Section
titleSpace 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.


Section
titleRender 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.


Section
titleMissing Content Message

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


Section
titleRender 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.

Transclusion
documentrender-transclusion-box
idsDescription


Transclusion
taget-heading-level*
documentTransclusion Macro
idsIdentifier



Section
titleRemove 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.


Section
titleExtract Short Description

Render the short description in front of the properties table.


Section
titleName as Heading

If checked renders the name of each transcluded document as heading. Requires target level to be set to a value between 1 and 6.


Section
titleHeading Link

If checked renders heading as link to the document.

If no heading is rendered, this flag has no effect.

Since version 1.11.


Section
titleAdd Link

If specified renders the label as link to the document.

The link is rendered after the possibly extracted short description and in front of the properties table.

Since version 1.11.


Section
titleSuppress Selection

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

Note Box

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



Section
titleReplacements

Specify the replacements in the macro's body.

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


...