projectdoc Toolbox 3.0 Release Notes

Support space properties in Where Clauses, Document Heading Numbering, and multi-transclusion fix.

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

This release provides some new features, improvements of existing features, and fixes some issues.

The projectdoc Toolbox is an add-on for Confluence supporting agile software development teams to collaborate on process, project, system, and product documentation. 

New and Noteworthy

Space Properties in Where Clause

This version supports replacing placeholders in Where Clauses with values from space properties. Previous versions only allowed to apply document properties.

Document Heading Numbering

The numbering of section headers is now including control over the document title as heading. Therefore it is now easier to start the numbering with the page title. It is also easier to define the starting level in case it is not the first section level.

The tip Using Heading Numbers introduces to the new features.

Link and Anchor Compatibility with Scroll Products

This version is better supporting the export pages with Scroll products. Intra-page links are resolved successfully.

See PDAC-1029 - Anchor Compatibility with Scroll Products Done for more information.

Alternative Texts

It is now possible to control the text shown for the Section Macro and the Display Table Macro in case the macro has an empty body.

See PDAC-1021 - No Content Text for Section Macro Done and PDAC-1019 - Add Alternative Text for No Hits Done for more information.

Multi-transclusion Fix

There has been an issue with calculating section levels for multi-transclusions. In case the sections selected for transclusion where not on the same level, the level of the section in the transcluded content has been wrong.

This version fixes this issue.

Breaking Changes

Key Summary T P Status Resolution Description
PDAC-1018 Remove Number Start Parameter from Section Macro New Feature Blocker (migrated) Done Fixed

We need to remove this feature since its definition is not sound and therefore the use cases are not very clear. If you need to control the starting level of a section, use PDAC-1017 Done .

PDAC-1029 Anchor Compatibility with Scroll Products New Feature Major Done Fixed

The main section identifier is set on the DIV element that encloses the section title and section body. Scroll products assume that the identifier is set to the header.

To be compatible with Scroll we will set the heading identifier (currently suffixed with "-head") to the main identifier (no suffix). The section DIV will be suffixed with "-start".

We also need to render an anchor for sections that hide their section title.

PDAC-1015 Section CSS Classes for Headings Improvement Major Done Fixed

The class hX is rendered for the base class used. We need to render this as projectdoc-base-h1 to make clear that this is the base level and not the current level. The CSS style sheet needs to updated accordingly.

Since the class named changed, this is a breaking API change.

We also need to add the CSS class 'projectdoc-heading' to each heading rendered by the Section Macro

PDAC-1011 Change Cache REST URL Improvement Minor (migrated) Done Fixed

The URL to the cache changes to find access to all caches under the URL .../caches/... .

PDAC-1014 Heading Level Adjustment in Multitransclusion broken Bug Critical (migrated) Done Fixed

Transclusion Macro fails to render the correct heading level if transcluding multiple sections at different levels.

The definition of the blank target heading level needs to be changed. While previously all headings are suppressed, we now need to only suppress the heading of the first section.

Known Issues

Transclusion of Hidden Sections

The handling of the transclusion of hidden sections has changed. As of this version, the section will no longer be transcluded. In a future version of the projectdoc toolbox, we will provide an option that allows transcluding hidden sections. In this version, it is necessary not to hide the section itself, but to surround it with a Content Marker Makro which itself is hidden.

All known issues are resolved in version 3.0.2.

Upgrade Instructions

Install the new OBR of the projectdoc Toolbox.

Due to PDAC-1024 - Fragment Cache and Heading Numbers Done you need to clear the fragments cache. In case you are using the fragments cache, refer to Cache Refresh Actions on how to refresh the cache.

No updates for extension add-ons or doctype add-ons are required.

List of Changes

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

Key Summary T P Status Resolution Description
PDAC-1018 Remove Number Start Parameter from Section Macro New Feature Blocker (migrated) Done Fixed

We need to remove this feature since its definition is not sound and therefore the use cases are not very clear. If you need to control the starting level of a section, use PDAC-1017 Done .

PDAC-1028 Localize Links in transcluded Content New Feature Critical (migrated) Done Fixed

Provide configuration options to the Section and Content Marker Macro to reconfigure links to targets inside the transcluded content.

PDAC-1023 Control Heading Numbering for Document Title New Feature Critical (migrated) Done Fixed

Use a space property / document property use-document-heading-number to control the numbering of the document title.

If the starting number is set to e.g. 4.2 then the title should be rendered with this number and the sections will follow with 4.2.1, 4.2.2, etc.

PDAC-1017 Hierarchical Heading Number Start New Feature Critical (migrated) Done Fixed

Support to control the heading level numbering to start with any level. This way it will be possible to start a section heading of level 2 with a two digits heading number (e.g. 2.1).

PDAC-1029 Anchor Compatibility with Scroll Products New Feature Major Done Fixed

The main section identifier is set on the DIV element that encloses the section title and section body. Scroll products assume that the identifier is set to the header.

To be compatible with Scroll we will set the heading identifier (currently suffixed with "-head") to the main identifier (no suffix). The section DIV will be suffixed with "-start".

We also need to render an anchor for sections that hide their section title.

PDAC-1027 Render Origin Locator in HTML New Feature Major Done Fixed

Each section and content should render its origin as data attributes. This way a HTML parser can determine where a content is transcluded from.

PDAC-1021 No Content Text for Section Macro New Feature Major Done Fixed

Allow to render a text inside a section if and only if the body of the section is empty.

This allows template authors to provide a standard text in case the author of the document has not (yet) provide content in the section body.

PDAC-1019 Add Alternative Text for No Hits New Feature Major Done Fixed

Provide a parameter to macros that hide if no hits are found in case no hits are shown. The parameter allows to provide custom text.

PDAC-1010 Provide Admin Access to Page Fragments Cache New Feature Major Done Fixed

Provide a REST service to access information in the page fragments cache.

Currently this is only for information, but may be extended to control access to the fragments remotely (especially clearing the cache).

Note that access is prohibited for users that do not have the admin role.

PDAC-1008 Apply Space Properties in Where Clause Improvement Critical (migrated) Done Fixed

When placeholders are used in a where clause of a macro and no document property matches, the macro should try to match space properties.

This is a natural extension to the use of page properties.

PDAC-1015 Section CSS Classes for Headings Improvement Major Done Fixed

The class hX is rendered for the base class used. We need to render this as projectdoc-base-h1 to make clear that this is the base level and not the current level. The CSS style sheet needs to updated accordingly.

Since the class named changed, this is a breaking API change.

We also need to add the CSS class 'projectdoc-heading' to each heading rendered by the Section Macro

PDAC-1009 Support Merging Plain HTML Lists Improvement Major Done Fixed

When merging property values via service we need not only support a list of macros and CSV, but also HTML lists ul and ol.

PDAC-1011 Change Cache REST URL Improvement Minor (migrated) Done Fixed

The URL to the cache changes to find access to all caches under the URL .../caches/... .

PDAC-1014 Heading Level Adjustment in Multitransclusion broken Bug Critical (migrated) Done Fixed

Transclusion Macro fails to render the correct heading level if transcluding multiple sections at different levels.

The definition of the blank target heading level needs to be changed. While previously all headings are suppressed, we now need to only suppress the heading of the first section.

PDAC-1025 Parameter Override Document Properties Marker Macro Bug Major Done Fixed

Override does not work if space property defines definition list and macro wants to override with table.

PDAC-1024 Fragment Cache and Heading Numbers Bug Major Done Fixed

The fragment cache must take into account whether or not the fragment contains CSS that triggers showing a heading number.

PDAC-1022 Suppress Mode for Section Numbering broken Bug Major Done Fixed

The suppress mode for doctypes to not show heading numbers on specified doctypes takes no effect.

PDAC-1016 Reset all Heading Counters Bug Major Done Fixed

Heading numbers fails to count levels correctly since not all levels are reset to zero.

PDAC-1013 Allow Boxes for Add-hoc Types when Space is specified Bug Major Done Fixed

When the Name List Macro provides a space key (with either of the two parameters) then the calculated doctype defaults to the 'default' doctype.

It should still use the doctype specified and make a lookup in the current page's delegate space.

PDAC-1012 Page Fragments Cache fails on Adding Document Title as Heading Bug Major Done Fixed

When the title of a document is added as heading to a cached page fragment, then this fragment is added on the wrong heading level. When fetching from the cache, the content of the fragment is one level too high.

PDAC-1030 Do not render empty Sections for Transclude Documents Bug Minor (migrated) Done Fixed

When sections are transcluded with the Transclude Documents Macro which are empty, then the rendered div element will provoke the rendering of the transclusion box.

We should suppress the rendering of empty div elements.

PDAC-1026 Attached Properties show Warning Bug Minor (migrated) Done Fixed

Attached properties from the Attachment Supplier should show "Preview not available" instead of a Warning.

PDAC-1020 Remove unused No Hits related Parameters from Name Body List Macro Bug Minor (migrated) Done Fixed

The parameters have no function.

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.