projectdoc Toolbox 4.2 Release Notes

Doctype as a Parameter, improved Support for Attachments, plus more new features, improvements, and bugfixes.

Today we released version 4.2 of the projectdoc Toolbox on the Atlassian Marketplace!

This release provides new features, improvements, and bugfixes.

The projectdoc Toolbox 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!

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.

Release Notes Overview

New and Noteworthy

Doctype as a Parameter

A projectdoc Document demands a Name and a Doctype to be set. All other document properties are recommended, especially the Short Description, but are not necessary.

Since Nameless Documents the name of a projectdoc Document may be derived from the Title. Since the title is mandatory for a Confluence page, the only property still required being part of the table within the Document Properties Marker Macro was the Doctype.

The Doctype property's value also needed to be provided in plain text. The projectdoc Toolbox does not a macro here since the value is required before any property value resolvement takes place.

This version of the projectdoc Toolbox allows to specify the doctype as a parameter to the Document Properties Marker Macro. This way the property cannot be accidentally be removed or changed. Since the property is hardly ever changed, it will not take space in the editor, too.

Note that a property with name Doctype still overrides any value set with the macro parameter. This is to ensure backward compatibility. It is not meant to be a standard use case.

Here is an example showing the doctype 'todo' as part of the macro.

When opening the macro in the editor, the Doctype parameter shows the type if the document.

Improved Attachment Support

The projectdoc Toolbox provides support to render the contents of an attached file. This allows template authors to design document types (blueprints) that show contents from files easily. From the moment a user attaches a document, the contents will automatically been shown.

Name Short Description Add-on
Attachment Link Macro
Renders a link to an attached file for download.
projectdoc Toolbox
Attachment Code Block Placeholder Macro
Renders a code block from an attached file with placeholders replaced by properties.
Information Systems Extension
Reference Attachment Code Block Placeholder Macro
Renders code of attached file, referenced by local property, with placeholders replaced by properties.
Information Systems Extension

The Attachment Link Macro makes it easy to reference an attachment as a property value. Use the Reference Attachment Code Block Placeholder Macro to render the attached file (or a part of the file) in a code box. In case there is no need to have the attached file as a property, use the Attachment Code Block Placeholder Macro.

The Autocomplete with this version also supports selecting attached files.

Layouting transcluded Content

When a transclusion macro renders content, the layout may be affected. This is typically because the transcluded content is rendered inside a HTML div element. This way CSS selectors on first element may not be applied or (not applied) as expected.

The users now can add additional CSS rules by referencing the selector "projectdoc-transcluded-content" which is rendered with the transcluded content.

Required Properties for Rendering

The Section Macro and the Content Marker Macro allow to control the rendering dependent on the evaluation of document and space properties. Prior to this version all listed properties have to meet the constraints (i.e. they were ANDed). With this version authors can specify that at least one property must match (i.e. they are now ANDed or ORed).

Currently we do not support more sophisticated queries using AND and OR in one specification.

Breaking Changes

This version has no breaking changes.

Upgrade Instructions

Install the new OBR of the projectdoc Toolbox, then the extensions listed below. After that the doctype add-ons starting with Core.

List of Changes

The following changes are part of the latest projectdoc Toolbox for Confluence. 

Key Summary T P Status Resolution Description
PDAC-1160 Render Link to attached File New Feature Critical (migrated) Done Fixed

Provide a macro that renders a download link to an attached file on the same document.
PDAC-1176 Provide Translation Service New Feature Major Done Fixed

Required to use this service outside the internal REST API.
PDAC-1170 Support Wizard Parameters in Doctype Model New Feature Major Done Fixed

Provide the wizard parameters set to the soy templates also at runtime to the Doctype Instance via the Doctype Service.

This information is required by e.g. REST services that create documents based on blueprints. This way the parameters can be applied in both contexts per default.
PDAC-1166 Add Selectors for Transcluded Content New Feature Major Done Fixed

Transcluded content may not fit nicely into the target location by adding or removing margin or padding. Thus the content is not easily to read.

We need to add selectors to allow users to adjust any inconvenient margins/paddings by selecting only on transcluded content.

Therefore each transclusion macro should add a class to the container rendering the transcluded content. This class is "projectdoc-transcluded-content".

This additional class would be provided by transclusion macros such as the Transclusion Macro and the Transclude Documents Macro.
PDAC-1165 I18N Bundle Support for JavaScript New Feature Major Done Fixed

Provide a REST service that allows JavaScript clients to create a translation bundle for a list of I18N keys.
PDAC-1164 Default Strategy for No Names New Feature Major Done Fixed

Provide a parameter to specify what to do to derive a default value for the Name List Macro in case there is no name specified.

The default is "none", but there is also "ancestor" (for searching an ancestor document like the Ancestor Macro), and "all" (like uncheck empty handling).
PDAC-1163 Support Autocomplete for Attachments New Feature Major Done Fixed

Provide an infrastructure to autocomplete names of attachments.

There is a service provided by Confluence, but we need to allow to have an optional value and set a name that does not yet exist.
PDAC-1156 Provide Default Doctype with Document Properties Marker Macro New Feature Major Done Fixed

Allow to set the doctype with the Document Properties Marker Macro by a parameter.

The parameter will remove one line from the properties table so that no properties may be empty. Since the Doctype property's constraint requires the value to be plain text, specifying it as a parameter is less error prone.

The Doctype property may still override the one specified with the parameter.
PDAC-1174 Render URL Property with an alternative Label Improvement Major Done Fixed

Provide a macro to render a link with a new label. The link is provided by a property and the new label is specified with the macro.

This allows to render a link to a resource referenced by a property with a label that is suitable for the context of the link.
PDAC-1173 Allow OR on Required Space Properties Improvement Major Done Fixed

We currently do not support complex checks on required space properties for the Content Marker Macro and the Section Macro. Only all matching propery use cases are supported.

Since the use case where any one of a list of properties is quite common, we should support this use case, too. To make this feature available without adding any new properties, we simply allow to switch semantics by setting a pipe character (|) as the first character of the parameter value:

value1,value2 => value1 or value2 or both must be present
value1,value2 => value1 and value2 must be present
PDAC-1172 Allow OR on Required Document Properties Improvement Major Done Fixed

We currently do not support complex checks on required document properties for the Content Marker Macro and the Section Macro. Only all matching propery use cases are supported.

Since the use case where any one of a list of properties is quite common, we should support this use case, too. To make this feature available without adding any new properties, we simply allow to switch semantics by setting a pipe character (|) as the first character of the parameter value:

value1,value2 => value1 or value2 or both must be present
value1,value2 => value1 and value2 must be present
PDAC-1162 Update for every Attachment Event Improvement Major Done Fixed

In case an attachment is updated, the document should be recalculated since properties might reference the new macro.

Currently we check if the property is marked, but this now seems not feasible any longer with the new Attachment Link Macro. Therefore we skip the is-relevant test. In case we encounter performance issues we would need to check this code again.
PDAC-1157 Add Tooltip Override Improvement Major Done Fixed

Provide a parameter to the Wiki Link Macro to allow to override the tooltip.
PDAC-1171 Merging with Placeholder Bug Major Done Fixed

When creating a projectdoc document merges initial values, a placeholder value must be considered an empty value.
PDAC-1178 Don't log Illegal Arguments Improvement Minor (migrated) Done Fixed

In case a macro rendering a code snippet signals illegal arguments, that exception must not be written to the log.
PDAC-1177 Render Error box properly Improvement Minor (migrated) Done Fixed
PDAC-1168 Allow to Workaround the first-child Issue Improvement Minor (migrated) Done Fixed

When the Content Marker Macro renders an identifier (or by any other means the macro requires to render an additional div element), the contents of the macro will probably be rendered as the first child of this container.

This may cause the application of CSS rules that now apply first-child styles, even if this macro is rendered logically not as a first child.

We add a feature to the macro so that the writer may configure the behavior. The value of a parameter, document property, or space property will control whether or not an additional span element is rendered thus making the content of this macro not its first child.

This feature is considered experimental.
PDAC-1175 Missing Autocomplete for Link Property Bug Minor (migrated) Done Fixed

The autocomplete feature is not available for the Link Property of the Display Document Property as Image Macro.
PDAC-1169 Split null value to empty list Bug Minor (migrated) Done Fixed
PDAC-1167 CSS Class for "No Permission Required" Bug Minor (migrated) Done Fixed

In case no permission is required to render content the macro renders a class name that is misleading.

The rendered class name is "permission-required" while it should render "no-permission-required".
PDAC-1158 Update Description for Required Properties Bug Minor (migrated) Done Fixed

The Section and Content Marker Macros allow to match a property value to be a required value, but the short description of the parameters (space and document) does not reflect this.
PDAC-1155 Fix Text Resources Bug Minor (migrated) Done Fixed

Fix double keys.
22 issues

Related Releases

Extension Add-ons

The following extensions are required to be updated for the projectdoc Toolbox.

All extensions are optional. In case an extension is not installed, there is no need to install it for this version of the projectdoc Toolbox.

Web API Extension

The following changes are part of the latest Web API Extension.

Key Summary T P Status Resolution Description
PDEXWAPI-45 I18N Translation REST Service New Feature Critical (migrated) Done Fixed

The service is copying the internal I18N service by making it part of the public Web API.
PDEXWAPI-40 Apply Wizard Parameters New Feature Major Done Fixed

REST services need to create documents based on blueprints the same way the standard wizard using soy templates does.

Since the information is now provided by the Doctype Maven Plugin, and made accessible by the projectdoc Toolbox 4.2, this information is now applied in the document creation process when called via REST.
PDEXWAPI-43 Support Replace Values for Patching a Property Improvement Major Done Fixed

Currently replacing value is not supported.
PDEXWAPI-42 Validate Document Arguments Improvement Major Done Fixed

Validate Input Documents. Properties must provide a name.
PDEXWAPI-44 Reassign the Space Key to the Parent Document Improvement Minor (migrated) Done Fixed

Confluence cannot create a page to a parent that is not in the same space.
PDEXWAPI-41 Obey Content Type on Error Bug Major Done Fixed

When an error is returned, the Web API always returns the result object in XML despite the selected content type.
6 issues

Bookmarklets Extension

The following changes are part of the latest Bookmarklets Extension.

Key Summary T P Status Resolution Description
PDEXBML-14 Bookmarklet Button Macro New Feature Critical (migrated) Done Fixed

Add a macro to provide a function to render a bookmarklet. This way it will be easy for readers on a bookmarklet page to add the bookmarklet to their bookmarks per drag-and-drop.
PDEXBML-12 Create Resource Bookmarklet New Feature Critical (migrated) Done Fixed

Add services to implement a bookmarklet to create a projectdoc document based on information from a remote web page.
PDEXBML-13 Remove Comments Improvement Major Done Fixed

Remove comments that start with the first character on a line.
PDEXBML-11 Bookmarklets JavaScript API Improvement Major Done Fixed

Provide an API for bookmarklets operating on the Confluence site. This should make it easier to develop bookmarklets.
4 issues

Information Systems Extension

The following changes are part of the latest Information Systems Extension.

Key Summary T P Status Resolution Description
PDEXINFOSY-33 Render Code from attached File New Feature Critical (migrated) Done Fixed

Allow to reference an attached file to show the code in a Code Macro.
PDEXINFOSY-32 Render Code from attached File referenced by a Property New Feature Critical (migrated) Done Fixed

Allow to reference an attached file via a property reference to show the code in a Code Macro.
PDEXINFOSY-31 Provide Space Property to Control Default Lines Parameter New Feature Major Done Fixed

For the transclusion macros allow to specify the value for the lines parameter by a space property named 'projectdoc.extension.information-systems.transclusion.lines'.
PDEXINFOSY-29 Allow Property to reference a remote File New Feature Major Done Fixed

The Text Snippet Macro and HTML Snippet Macro allow to transclude content via an URL. These macros should provide an additional parameter allowing to specify a property that holds the URL as value.
PDEXINFOSY-30 Default for Autoconvert Check Parameter New Feature Minor (migrated) Done Fixed

Provide a space property that controls whether or not the check parameter of a System Link Macro should be set per default or not.
PDEXINFOSY-35 Allow Start Snippet-ID only Improvement Major Done Fixed

Allow to find only the Snippet Start ID and then run to the end of the file.
PDEXINFOSY-34 Render Error box properly Improvement Minor (migrated) Done Fixed
PDEXINFOSY-36 Don't log Illegal Arguments Bug Minor (migrated) Done Fixed

In case a macro rendering a code snippet signals illegal arguments, that exception must not be written to the log.
8 issues

Doctype Add-ons

The following doctype add-ons are recommended to be updated for the projectdoc Toolbox.

All doctype add-ons are optional. In case an add-on is not installed, there is no need to install it for this version of the projectdoc Toolbox.

Core Doctypes

The following changes are part of the latest Core Doctypes Add-on. 

Key Summary T P Status Resolution Description
PDCORED-255 Provide Doctype per Parameter New Feature Major Done Fixed

Define the doctype property as macro parameter instead of as a row in the properties table. Requires the projectdoc Toolbox 4.2.
PDCORED-257 Compatibility Update for Version Doctype Improvement Blocker (migrated) Done Fixed

The update is required for projectdoc Toolbox 4.2. The update sets a property to control the creation of correct titles for the Version Doctype.
PDCORED-256 Fix I18N key for "Source" Bug Minor (migrated) Done Fixed

The resource doctype provides a property named "Source" with a copy-paste issue in its I18N key. The key 'projectdoc.doctype.resource.quelle' needs to be renamed to 'projectdoc.doctype.resource.source'.
3 issues

Doctypes for Agile Planning

The following changes are part of the latest Doctypes for Agile Planning.

Key Summary T P Status Resolution Description
PDAGILE-84 Provide Doctype per Parameter New Feature Major Done Fixed

Define the doctype property as macro parameter instead of as a row in the properties table. Requires the projectdoc Toolbox 4.2.
1 issue

projectdoc Developer Diaries

The following changes are part of the latest projectdoc Developer Diaries.

Key Summary T P Status Resolution Description
DEVDIARY-120 Provide Doctype per Parameter New Feature Major Done Fixed

Define the doctype property as macro parameter instead of as a row in the properties table. Requires the projectdoc Toolbox 4.2.
1 issue

Doctypes for Project Management

The following changes are part of the latest Doctypes for Project Management.

Key Summary T P Status Resolution Description
PDPRJMGMT-67 Provide Doctype per Parameter New Feature Major Done Fixed

Define the doctype property as macro parameter instead of as a row in the properties table. Requires the projectdoc Toolbox 4.2.
1 issue

Doctypes for Service Management

The following changes are part of the latest Doctypes for Service Management.

Key Summary T P Status Resolution Description
SERVICES-15 Provide Doctype per Parameter New Feature Major Done Fixed

Define the doctype property as macro parameter instead of as a row in the properties table. Requires the projectdoc Toolbox 4.2.
SERVICES-14 Support empty Aside Panels Improvement Major Done Fixed

Redesign the integration of the Aside Panel Macro to allow hiding empty panels.
SERVICES-13 Support Short Name Queries Improvement Major Done Fixed

Allow to query for Names and Short Names alike with type doctypes.
SERVICES-12 Add IDs Home/Index Page Boxes Improvement Major Done Fixed

The boxes on home pages and index pages need to provide a unique identifier to refer to these boxes individually from CSS.
4 issues

Doctypes for Business Strategy

The following changes are part of the latest Doctypes for Business Strategy.

Key Summary T P Status Resolution Description
STRATEGY-16 Provide Doctype per Parameter New Feature Major Done Fixed

Define the doctype property as macro parameter instead of as a row in the properties table. Requires the projectdoc Toolbox 4.2.
STRATEGY-15 Support empty Aside Panels Improvement Major Done Fixed

Redesign the integration of the Aside Panel Macro to allow hiding empty panels.
STRATEGY-14 Support Short Name Queries Improvement Major Done Fixed

Allow to query for Names and Short Names alike with type doctypes.
STRATEGY-13 Add IDs Home/Index Page Boxes Improvement Major Done Fixed

The boxes on home pages and index pages need to provide a unique identifier to refer to these boxes individually from CSS.
4 issues

Doctypes for Software Development

The following changes are part of the latest Software Development Doctypes.

Key Summary T P Status Resolution Description
PDSWDEVD-136 Provide Doctype per Parameter New Feature Major Done Fixed

Define the doctype property as macro parameter instead of as a row in the properties table. Requires the projectdoc Toolbox 4.2.
1 issue

Doctypes for Teamwork

The following changes are part of the latest Doctypes for Teamwork.

Key Summary T P Status Resolution Description
PDTEAMWORK-23 Provide Doctype per Parameter New Feature Major Done Fixed

Define the doctype property as macro parameter instead of as a row in the properties table. Requires the projectdoc Toolbox 4.2.
1 issue

Doctypes for V-Modell XT

The following changes are part of the latest Doctypes for V-Modell XT.

Key Summary T P Status Resolution Description
PDVMXT-24 Provide Doctype per Parameter New Feature Major Done Fixed

Define the doctype property as macro parameter instead of as a row in the properties table. Requires the projectdoc Toolbox 4.2.
1 issue

projectdoc arc42 Template

The following changes are part of the latest projectdoc Add-on for arc42.

Key Summary T P Status Resolution Description
ARCFOURTWO-71 Provide Doctype per Parameter New Feature Major Done Fixed

Define the doctype property as macro parameter instead of as a row in the properties table. Requires the projectdoc Toolbox 4.2.
ARCFOURTWO-68 Support empty Aside Panels Improvement Major Done Fixed

Redesign the integration of the Aside Panel Macro to allow hiding empty panels.
ARCFOURTWO-67 Add IDs Home/Index Page Boxes Improvement Major Done Fixed

The boxes on home pages and index pages need to provide a unique identifier to refer to these boxes individually from CSS.
ARCFOURTWO-69 Remove hard-coded Intro Text Improvement Minor (migrated) Done Fixed

By removing the hard coded intro text the boxes on the Home and Index Pages are shorter.
4 issues

Doctypes for Java Developers

The following changes are part of the latest projectdoc for Java Developers.

This extension is experimental.

Key Summary T P Status Resolution Description
PDJAVADEV-25 Provide Doctype per Parameter New Feature Major Done Fixed

Define the doctype property as macro parameter instead of as a row in the properties table.

Requires the projectdoc Toolbox 4.2.
PDJAVADEV-26 Compatibility Update for Version Doctype Improvement Critical (migrated) Done Fixed

The update is required for projectdoc Toolbox 4.2. The update sets a property to control the creation of correct titles for the Version Doctype (used by the Space Blueprint).
2 issues

Doctypes for Maven Developers

The following changes are part of the latest projectdoc for Maven Developers.

This extension is experimental.

Key Summary T P Status Resolution Description
PDMVNDEV-22 Provide Doctype per Parameter New Feature Major Done Fixed

Define the doctype property as macro parameter instead of as a row in the properties table.

Requires the projectdoc Toolbox 4.2.
PDMVNDEV-25 Compatibility Update for Version Doctype Improvement Critical (migrated) Done Fixed

The update is required for projectdoc Toolbox 4.2. The update sets a property to control the creation of correct titles for the Version Doctype (used by the Space Blueprint).
PDMVNDEV-24 SwDev Create Labels Bug Major Done Fixed

Fix the keys to create button labels for template imported from the SWDEV add-on.
PDMVNDEV-23 Create Space Blueprints Bug Major Done Fixed

Soy template uses outdated blueprint keys.
4 issues

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.