Property Supplier Macro, Placeholders in Space Properties, Transclusion from Confluence Pages, Extension Support, and Heading Level for Sections
Today we released version 1.11 of the projectdoc Toolbox on the Atlassian Marketplace!
projectdoc is an add-on for Confluence supporting agile software development teams to collaborate on process, project, system, and product documentation.
If you want to learn more about the projectdoc Toolbox and how it helps to create good project documentation, please refer to the introduction video!
The following image is a link to a video on YouTube. When you click the link your browser will serve a page from youtube.com
.
Very interesting, but way too fast?
Step through at your own pace with with our Prezi Presentation (external link to prezi.com
)!
In the Online Manual you’ll find additional video material that introduces you in the concepts of the projectdoc Toolbox.
Refer to use cases and show cases for information on how to use the projectdoc Toolbox.
New and Noteworthy
The following changes may be the most interesting of this release.
Property Supplier Macro
With this version it is now very easy to specify document properties in separate tables. This makes it possible to group properties semantically and show them on different locations of the page.
There is still one Document Properties Marker Macro required, but there can be any number of additional Document Properties Supplier Macros. The author is still responsible to make sure that each property is provided only once.
Document Properties as Data provides a tip on using the Document Properties Supplier Macro.
Placeholders in Space Properties
It is now very easy to references space properties within a space property value. Just use ${name}
where name
refers to another space property.
A typical usage scenario is to define the version of a product and reuse this information within other space properties.
url-scm=https://bitbucket.org/smartics
project.artifactId=smartics-projectdoc-confluence-space-core
project.version=5.1.0
url-download-sources=${url-scm}/${project.artifactId}/get/${project.artifactId}-${project.version}.zip
Using Space Properties provides tips on working with space properties.
Extension Support
We have learned that users of the projectdoc Toolbox are overwhelmed its the features. While being feature rich is a good thing, overwhelming is not. Therefore we decided to move some of the core features to extensions. This way users can better decide which features they want to install and which not.
With this release the support for information systems integration and for Maven moved to extensions.
- Information Systems Extension
- Add-on to extend the projectdoc Toolbox to integrate remote information systems.
- Maven Extension
- Add-on to extend projectdoc for Confluence with Maven Tools.
If you relay on the information systems' macros or the Maven support, please make sure to upgrade to 1.11 of the projectdoc Toolbox once these extensions are publicly available!
Both extensions are free to use and installed as additional add-ons to the required projectdoc Toolbox.
Information Systems Extension
Due to the introduction of placeholders in space properties, referring to resources on remote information systems is now much easier. Macros that solely provided means to construct URLs out of several parts are now deprecated and will be removed with one of the next releases.
The most important feature of this release is the support for autoconversion. Every URL that is defined as an external resource will be automatically converted to a macro. This makes it very easy to replace the base URL to an information system in case the system moved to another location.
For more information on working with remote information systems, please refer to Information Systems Extension.
Maven Extension
The Maven Extension and the related doctype add-ons have been removed in 2025.
It is recommended to generate the information in other information systems (for instance Maven Sites) and then link from Confluence to these pages.
The Maven Extension provides tools to create spaces and pages based on artifact information. Currently information is read from POMs, buildmetadata, and Maven Plugin Descriptors.
Transclusion from Confluence Pages
Prior version of the projectdoc Toolbox required the transcluding and the transcluded page to be projectdoc documents. With version 1.11 both ends of the transclusion may now be Confluence pages. That is: neither page needs to have the Document Properties Marker Macro.
Heading Level for Sections
With this version of the projectdoc Toolbox the starting level of sections can be configured per space. That is: the team may decide whether the titles of the top-level sections are rendered as h1
or h2
.
The rendering is controlled by the space property Heading Starting Level.
Control on Name Selection
The Name List Macro now allows the template author to restrict the selection of names. By configuration of the macro the user is aware to choose only one value or values from a given range.
Breaking Changes
The following changes are incompatible with the previous release.
Doctype Add-on Update required
Due to
PDAC-631
-
Force User to select from Value Range
Done
it is required to update the doctype add-ons for the projectdoc Toolbox.
List of Changes
The complete list of changes for this release.
The following changes are part of the latest projectdoc Toolbox for Confluence.
Key | Summary | T | P | Status | Resolution | Description |
---|---|---|---|---|---|---|
PDAC-639 | Replace with Space Properties for Blueprints |
|
|
Done | Fixed |
Allow to replace placeholders in form fields with space property values. |
PDAC-637 | Template Replacer Service |
|
|
Done | Fixed |
Provide a service via HTTP that allows template authors to replace placeholders in input for form fields. |
PDAC-635 | Transclusion from Confluence Pages |
|
|
Done | Fixed |
Most macros of the projectdoc Toolbox only work with projectdoc document. While it is not difficult to transform Confluence page to a projectdoc document, new users typically do no know this constraint. When they try the toolbox, they will almost immediately fall into this trap. Therefore we should enhance the error messages once a user tries to use macros relying on the Properties Document Marker Macro. And we should enhance macros to actually deal with Confluence pages. The Transclusion Macro is one of them. While there are features that can only be provided by accessing document properties, others should work (maybe with some limitations) without. We should allow transclusions from sections and content regardless of the transcluded source entity is a Confluence page or projectdoc document. |
PDAC-634 | Document Property Supplier Macro |
|
|
Done | Fixed |
Provide means to add properties for a document not only by the Document Properties Marker Macro. We want to make it easier for document authors to group properties and add additional text for these properties. While we looked at document properties mainly as metadata, allowing to separate and display these properties will make it easier for authors to deal with properties as content (not only metadata). Authors are responsible to ensure that no property name is used more than once. |
PDAC-624 | Allow Placeholders in Space Properties |
|
|
Done | Fixed |
Allow to simplify referencing space properties in space property values. Use the ${property-name} syntax to resolve references. |
PDAC-622 | Extract Information System Macros |
|
|
Done | Fixed |
Move all macros that access information on remote servers (per link or transclusion) to its own extension. |
PDAC-620 | Space Property for Section Heading Starting Level |
|
|
Done | Fixed |
Sections should allow to define the base level of sections if the level is set to '*'. Currently the system assumes the level of 1, but a variable selection would make it easier for teams to switch between h1 and h2 based documents. |
PDAC-644 | Support Creation Tracking |
|
![]() |
Done | Fixed |
Creating spaces and pages with plenty of subpages takes a considerable amount of time. Therefore we need some infrastructure to track the advancement of these processes to display them to the users. |
PDAC-642 | Render Link for Display Table And Transclude Documents Macro |
|
![]() |
Done | Fixed |
Links are typically rendered with the name of the document. The name is always rendered in the result table. For some use cases it is not appropriate to render the name in the table.Therefore we need controls to render a link to the document the information is transcluded from. One is to render the heading as link. But since this might not get well with every style guide, we also need to specify a label that is rendered after the short description (if present) and before the table of properties. |
PDAC-636 | Refresh Tree Action Supports Changes Bottom Up |
|
![]() |
Done | Fixed |
Using the Refresh Page Tree Action changes of page properties are only propagated from a page down to its children. This feature enables the propagation in both directions. |
PDAC-631 | Force User to select from Value Range |
|
![]() |
Done | Fixed |
The Name List Macro (and the Tag List Macro) allow users to specify arbitrary values and does not force to select from a predefined value range. While it is a valid use case to allow arbitrary values we should allow the template author to force the use of a range. If the author selects a value out of range, the value is simply rejected. |
PDAC-630 | Force User to select one Property Value |
|
![]() |
Done | Fixed |
The Name List Macro (and Tag List Macro) have no control on the number of values to choose. A common use case is to require only one property to be set. Therefore we should add a parameter that limits the number of valid selections to 1. We should discuss if a max value would support more use cases ("choose up to three!"), but this would probably make the UI more complicated for the default use case. |
PDAC-626 | Configure Property Table Rendering for Index Cards |
|
![]() |
Done | Fixed |
Allow to configure the mode for rendering the properties of a index card. Currently it is only possible to render a plain table. We need to allow to pass in a CSS class and allow to choose between table and definition list style. |
PDAC-623 | Add Where to Index Macros |
|
![]() |
Done | Fixed |
Add Where Parameter to Index Macros to select on result sets. |
PDAC-619 | Support XHTML Properties in Wizards |
|
![]() |
Done | Fixed |
Properties that are rendered as raw XHTML have to be normalized. This is especially relevant for values containing character entities like "clever & smart". |
PDAC-640 | Improved Context Provider API |
|
|
Done | Fixed |
Provide a support class to help keeping the Context Provider API more stable. |
PDAC-212 | Support Transitive Property Updates |
|
|
Done | Fixed |
The update is currently not transitive and therefore document properties that reference document property values transitively do not get updated. |
PDAC-641 | Allow to Suppress Transclusion Box for Display Table Macro |
|
![]() |
Done | Fixed |
Currently there is no option for the Display Table Macro to suppress the rendering of the transclusion box. It should be available since otherwise users may only switch the rendering off on space-level. |
PDAC-621 | Extract Maven Dependencies |
|
![]() |
Done | Fixed |
To reduce the dependencies and therefore shrink the size of the OBR we remove the Maven dependencies and move them to their own extension add-on. |
PDAC-625 | Right-align Counter Columns |
|
|
Done | Fixed |
Tables rendered with a counter column should right-align the counter value. |
PDAC-633 | Role List with no Permission fails |
|
![]() |
Done | Fixed |
The Role List Macro runs into a NPE if no permission is set on a page. |
PDAC-629 | Blueprint Wizards for Type do not check Form Input |
|
![]() |
Done | Fixed |
The type doctypes experience level, module type, resource type, and topic type do not check the form fields when creation a doctype instance with the blueprint wizard. |
PDAC-628 | Transclusion Box Link Name not resolved |
|
![]() |
Done | Fixed |
Rendering the transclusion box for documents without a plain name fails. If the name contains macros, the name is not resolved. |
PDAC-627 | Property Fetching includes Parent Pages |
|
![]() |
Done | Fixed |
The property fetcher not only fetches from the current document, but also from its parent pages. There are no semantics to fetch from the parent pages and therefore we should only return the document properties from the document itself. |
PDAC-643 | Counter Column interferes with Column Rendering |
|
|
Done | Fixed |
When a column is configured to render e.g. center aligned, switching on the counter column influences the column locator. The render options are then applied to the column left of the specified one. |
PDAC-638 | Missing Support of HTML Entities for Section Macro in Edit Mode |
|
|
Done | Fixed |
The Section Macro does not support HTML entities in its placeholder image diplayed in edit mode. |
Resources
- Release Notes for the projectdoc Toolbox
- Relevant information on changes to the projectdoc Toolbox for Confluence introduces by new versions of this app.
- Glossary
- Terms used in and defined for projectdoc.
- FAQs
- Questions and answers related to the projectdoc Toolbox and Confluence.