projectdoc Toolbox

Renders transcluded content fetched from documents of a result set.

Audience

Author, Template Author

Categories

Display / Query

Tags

Type

Dynamic Navigation

Since

1.10

Page Size Support

Renders part of documents for a given type in an index structure.

Use this macro to render a collection of selected documents on a single page.

This is similar to the generic Transclude Documents Macro, but preconfigured for rendering indices. It is easier to specify the elements to be part of the index by adding the document names to the body of the macro.

Unlike the Index Entries Table Macro the Index Card Macro renders each entry as an excerpt.

Properties

Doctype(s)

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.

This is a specialized version of the Transclude Documents Macro with predefined parameters to match the use cases for listing documents.

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):

Option	Description	Example
`-`	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.

Identifiers	Description
`-Description`	Render 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.

Identifiers	Description
`-Description, *, !References`	Render every section, but the references section and suppress the heading of the description section.

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.

Use Deep Link to select a property from a referenced document in the Select Clause.

Name, Audience->Group, Audience

The table header can be replaced using the Header Translations parameter by most macros

Audience->Group=Group Name

Since 4.13

Since version 4.13 the parameter supports to reference a space property. The name of the space property has to be prefixed with the paragraph sign ('§').

For instance, if the value for the select parameter is specified by the space property my-select, then the value of the select parameter is §my-select.

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.

Since 4.13

Since version 4.13 the parameter supports to reference a space property. The name of the space property has to be prefixed with the paragraph sign ('§').

For instance, if the value for the where parameter is specified by the space property my-where, then the value of the select parameter is §my-where.

Available since version 1.11.

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.

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.

Transitive Transclusion

If Transitive Transclusion is checked then transclusion from transcluded content is allowed.

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

Removed since 7.0

Since version 7.0 the transclusion from transcluded content is activated per default and cannot be deactivated.

Separator

The default separator for the index items specified in the body of this macro is the comma (','). The items may be specified on multiple lines, but each line is split by the commas in this line.

If your index entries have commas in their names, the separator may defined to something different than a comma. If you have one entry on each line, specify '\n' as a special separator. Note that a separator can only have one character. The special separator for newlines is an exception.

Available since version 1.17.

Insert Short Name Entries

If a value different to none is selected, an additional entry is added for each entry that has a short name or an abbreviation.

Value	Description
`none`	No additional values are added.
`short-name`	Additional entry for the Short Name is added.
`abbreviation`	Additional entry for the Abbreviation is added.
`all`	Additional entry for Short Name and Abbreviation is added.

Additional entries render a link with a reference to the main entry (identified by the document name).

Render Index

Render sections for index keys.

The elements associated with an index key are enclosed in an element and the index key is rendered.

CSS Class	Description
`div.projectdoc-index`	The block around the table of index entries.
`span.projectdoc-index`	The text rendering the index key.

The default styles are:

div.projectdoc-index {
  margin-top: 2em;
}

span.projectdoc-index {
  font-size: larger;
  font-weight: bold;
}

Render Index Access Panel

Render links to index keys above the index for quick access of the index key from the top of the page.

The value of this parameter is only taken into account, when Render Index is selected.

The default styles are:

div.projectdoc-index-access-panel {
    border-radius: 10px;
    border: 2px solid #036;
}

.projectdoc-index-access-panel ul {
    margin: 3px;
    padding: 3px;
    list-style-type: none;
    text-align: center;
}

.projectdoc-index-access-panel ul li {
    display: inline;
}

.projectdoc-index-access-panel ul li a {
    border-radius: 10px;
    text-decoration: none;
    padding: .2em 1em;
    color: white;
    font-weight: bold;
    background-color: #369;
}

.projectdoc-index-access-panel ul li a:visited {
    color: white;
    background-color: #369;
}

.projectdoc-index-access-panel ul li a:link {
    color: white;
    background-color: #369;
}

.projectdoc-index-access-panel ul li a:hover {
    color: white;
    background-color: #036;
}

Render Mode

Controls how the table should render properties of the document result set.

There are two render modes: table, definition list

Available since version 1.11.

Table Render Mode

If you want to render the result in a table, leave this parameter value blank. You may also explicitly set this value to table.

Add a CSS class by separating it with a "=".

=mystyle
table=mystyle

Definition List Render Mode

Set the value to definition to render the properties as a definition list.

You may add a CSS class by separating it with a "=".

definition=mystyle

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.

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.

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.

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.

Restrict to immediate Children

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

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.

Replacements

Specify the document names and replacements in the macro's body.

Lines without '=' are lists of document names to select.
Placeholder/replacement pairs, separated by an '=' character.

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 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.
Transclude Documents Macro: Renders transcluded content fetched from documents of a result set.
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.

References

Limitations on Query Results: The number of hits for document queries is limited due to performance reasons.

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.

Space shortcuts

Page tree

Docs

Support

Free Blueprints

Tooling for Blueprints

Free Extensions

Spaces

Plugins for Maven

Incubator

Libraries for Java