projectdoc Toolbox 1.13.0 Release Notes

Improved Support for Templates, Support for Web API, improved Transclusions

Today we released version 1.13.0 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. 

Summary

New and Noteworthy

The following changes may be the most interesting of this release.

Web API Support

The Web API Extension in version 1.1 now supports write access to projectdoc documents. This version of the projectdoc Toolbox is providing services for this extension.

Key Summary T P Status Resolution Description
PDEXWAPI-1 Support Document Manipulation New Feature Critical (migrated) Done Fixed

Provide services to change projectdoc documents.

PDEXWAPI-2 Cache Refresh Improvement Critical (migrated) Done Fixed

We need to signal that clients need to check for updated content. Currently we simply set the last modification time and (for Confluence 5.10.x) the ETag.

Now we need to set the CacheControl to instruct clients to revalidate.

PDEXWAPI-3 Breaking CDATA Blocks Bug Blocker (migrated) Done Fixed

Updating a page with the API removes CDATA blocks from the page. This corrupts for instance the Code Macro or the HTML macro.

Before:

<ac:plain-text-body><![CDATA[<a class="aui-button sharelinks-urlmacro-button" href="a"><span>reader</span></a>
<a class="aui-button sharelinks-urlmacro-button" href="b"><span>writer</span></a>
<a class="aui-button sharelinks-urlmacro-button" href="c"><span>printer</span></a>]]></ac:plain-text-body>

After:

<ac:plain-text-body>&lt;a class=&quot;aui-button sharelinks-urlmacro-button&quot; href=&quot;a&quot;&gt;&lt;span&gt;reader&lt;/span&gt;&lt;/a&gt;
&lt;a class=&quot;aui-button sharelinks-urlmacro-button&quot; href=&quot;b&quot;&gt;&lt;span&gt;writer&lt;/span&gt;&lt;/a&gt;
&lt;a class=&quot;aui-button sharelinks-urlmacro-button&quot; href=&quot;c&quot;&gt;&lt;span&gt;printer&lt;/span&gt;&lt;/a&gt;</ac:plain-text-body>

Enhanced Remote Transclusion

The Information Systems Extension in version 1.1 supports Transclusion of HTML fragments.

Key Summary T P Status Resolution Description
PDEXINFOSY-9 HTML System Transclusion New Feature Critical (migrated) Done Fixed

Support transclusion from XML/HTML documents by query.

PDEXINFOSY-8 HTML Element Transclusion Macro New Feature Critical (migrated) Done Fixed

Allow to transclude HTML content from a remote server by ID and selector.

PDEXINFOSY-10 Allow Rendering of Full URL Improvement Major Done Fixed

For the generic and site link macros allow to render the full URL instead of the last part of the URL.

PDEXINFOSY-11 Suppress Duplicate Slash in URL Rendering Bug Major Done Fixed

If either the system URL ends with a slash or the file starts with a slash then do not render an additional slash.

Template Support

This version allows users to create user templates with projectdoc macros. The way previous versions of the projectdoc Toolbox handled previews prevented the template editor from being used.

Please note that the source editor often still corrupts the template source, so its use is not recommended.

The free projectdoc blueprints typically use variables inside macro definitions. This does not cause any problems when used outside the template editor. The template editor does not allow placeholders inside macro definitions, so it will corrupt templates that use them. Therefore: do not edit blueprint templates that use placeholders with the template editor!

Breaking Changes

The following changes are incompatible with the previous release.

Disblock Property Values per Default

Since the Confluence editor may add a number of block elements without giving the user means to edit it (without the source editor plugin) we decided to run some automatic correction per default.

The correction will normalize the property value prior to saving it. The normalization will remove redundant div and p elements.

This will make it easier for users to get what they want.

If the property value is indeed a block element, the new control is-block will prevent the element from being disblocked.

If users are generally unhappy with this breaking change, the system property prevent-disblocking-property-values will help them to switch this off. This system property needs to be set on start time of the Confluence server.

Note that since we will now remove the blocks per default, we may break the runtime behavior. If a user really needs the block element s/he may either save the value with the is-block control or needs to switch off this feature with the system property.

See PDAC-676 - Disblock Property Values per Default Done for tracking this issue.

Last Version and Last Version Comment

Since is a number of new artificial properties, existing documents need to be indexed to have these properties available.

Users who do not access these values or only require them for new documents do not need to run the reindex.

See PDAC-693 - Provide Access to Last Version and Last Version Comment Done for tracking this issue.

Upgrade Instructions

The following topics have to be considered for an upgrade to this version.

It is recommended to update extensions and doctype add-ons to the latest versions.

Add-onTypeVersion
Web API ExtensionExtension1.1
Information Systems ExtensionExtension1.1
Maven ExtensionExtension1.0.2
Core DoctypesBlueprints6.1.0
Software Development DoctypesBlueprints6.0.2
projectdoc Add-on for arc42Blueprints4.1.1
Developer DiariesBlueprints4.0.2
Doctypes for Agile PlanningBlueprints5.0.1
projectdoc for Maven DevelopersBlueprints2.0.1
projectdoc for Java DevelopersBlueprints2.1.0

Please note that the Doctypes for Project Management are available soon!

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-690 Support Template Previews for Document Properties Marker Macro New Feature Critical (migrated) Done Fixed

We should consider to provide previews for the Document Properties Marker Macro in the context of the template editor. Otherwise it cannot provide access to the template variables.

PDAC-676 Disblock Property Values per Default New Feature Critical (migrated) Done Fixed

Since the editor may add a number of block elements without giving the user to edit it (without the source editor plugin) we should run the correction per default.

The correction will normalize the property value prior to saving it. The normalization will remove redundant div and p elements.

This will make it easier for users to get what they want.

If the property value is indeed a block element, the new control is-block will prevent the element from being disblocked.

If users are generally unhappy with this breaking change, a system property will help them to switch this off. This system property needs to be set on start time of the Confluence server.

Note that since we will now remove the blocks per default, we may break the runtime behaviour. If a user really needs the block element s/he may either save the value with the is-block control or needs to switch off this feature with the system property.

PDAC-695 Allow multiple References in the Reference Property Macro New Feature Major Done Fixed

If the referencing property refers to multiple documents, we should render the referenced property of all documents.

PDAC-692 Provide Page Preview for Document Properties Marker Macro New Feature Major Done Fixed

Preview of properties should help users to check updates to properties.

PDAC-682 Version the automatic Store of a Page New Feature Major Done Fixed

Currently all automatic stores will write over the current version. With the advent of the web api we need to make sure that users can roll back the versions created with this api.

PDAC-680 Index Heading Print Quirk Mode New Feature Major Done Fixed

Provide a print quirk mode for rendering the index in h1 elements (instead of span).

PDAC-671 Support Property References in Transclusion Macros New Feature Major Done Fixed

The Transclusion Macro and the Transclude Documents Macro supports placeholders with simple key-value mappings. We should also support to have a property reference as a value which is resolved in the context of the transcluding page.

PDAC-670 Transclusion with Page and Space Properties New Feature Major Done Fixed

It should be possible to employ document and space properties from the document that is using the Transclusion Macros as values for placeholders.

PDAC-693 Provide Access to Last Version and Last Version Comment New Feature Minor (migrated) Done Fixed

Add Version Number, Version Comment, Last Version Comment, and Last Version Number with Comment as artificial properties.

PDAC-683 Typed Parent Calculation bent to Confluence Parent Hierarchy Improvement Critical (migrated) Done Fixed

The typed hierarchy of parents is currently bound to the Confluence page hierarchy. It simply a filter on that hierarchy that matches the doctype of the parent document. If it is the same, the parent is accepted as typed parent, otherwise it is not and the calculation stops.

But the Parent Property of projectdoc does not need to be related to this hierarchy. The parent may reference any other document and so identifies this page as its logical parent.

The value of the Parent Property may either be a regular Confluence link or it may be the Parent Property or the Display Property Macro. These references should be accepted to create the artificial properties AncestorTypeNames and (new) AncestorTypeIds.

PDAC-696 Ancestors should not contain the Document Improvement Major Done Fixed

The list of ancestors should only contain the ancestors, not the document whose ancestor list this is.

PDAC-691 Allow Preview of Sections in Template Editor Improvement Major Done Fixed

The Section Macro fails to render in the preview of the template editor.

PDAC-685 Add Box Titles to Lucene Index Improvement Major Done Fixed

The titles of box macros are not added to the Lucene index and therefore not searchable.

We need to handle the titles of boxes as we handle the titles of sections.

PDAC-678 Allow composed Space Properties for Code Macro Improvement Major Done Fixed

Currently the Code Macro does not resolve space properties that contain space property placeholders. But these templates should be resolved as it is done by the Display Space Property Macro.

Meanwhile composed space property values can only be created by the use of the display space property macro.

PDAC-668 Allow to override Attribute Names in Space List Macro Improvement Major Done Fixed

To be similar to the Display Table Macro also allow heading translations for the Space List Macro. Simply specify, e.g., title=My Title to render My Title instead of the localized translation of title.

Also allow to set the empty string.

PDAC-667 Allow Spaces to be selected with AND using the Space List Macro Improvement Major Done Fixed

The space list macro only allows to specify a list of categories where any category may match to select a space. We should allow to specify categories where a space has to match all of them to be selected.

PDAC-699 Support References for Quote Documents Improvement Minor (migrated) Done Fixed

The quote macro has to consider a reference provided by the quote doctype. This makes it easier to create referenceable documents containing quotes.

PDAC-698 Quote Date without Brackets Improvement Minor (migrated) Done Fixed

Provide a space property to control the rendering of brackets around the date of the quote macro. If the date is rendered using the date picker, the additional brackets need to be removeable.

PDAC-665 CSS Class for Sections without Title Improvement Minor (migrated) Done Fixed

To allow specific handling of sections that have their title suppressed, render a CSS class.

PDAC-681 Page Manipulator cannot handle CDATA Bug Critical (migrated) Done Fixed

When the page manipulator parses a page the CDATA blocks are transformed to escaped entity text. This breaks for instance macros that contain CDATA blocks and after the page is written do not recognize these blocks any longer.

We need to encode the CDATA blocks so that the underlying parser cannot corrupt the page content.

PDAC-672 Page Property Generation Bug Critical (migrated) Done Won't Fix

Due to an API change projectdoc does not provide the document properties as page properties.

PDAC-701 Level Calculation for Transclusion fails Bug Major Done Fixed

Transcluding documents fails to render the 0-heading correctly. The heading is rendered at level 1 instead of suppressing the heading.

PDAC-697 Quote Authors not collected with Lucene Bug Major Done Fixed

When Lucene runs the rendering to index a page, the references to quote authors are not calculated.

PDAC-694 Render as Definition List Bug Major Done Fixed

Setting definition list as render option for the Document Properties Marker Macro does not always render a definition list.

PDAC-689 Template Preview renders wrong Message Bug Major Done Fixed

The Document Properties Marker Macro renders an error message indicating that there is no document to be rendered when the preview of a template is shown.

Since projectdoc currently does not support previews, the message should just state that.

PDAC-686 Prevent Section Titles of empty Sections from being indexed Bug Major Done Fixed

If the section contains only a placeholder, the body is effectively empty, but the section is considered non-empty.

This results in titles of empty sections to show up in the index.

PDAC-684 Dots in Section and Content Marker IDs Bug Major Done Fixed

If the identifier of the Section Macro or the Content Marker Macro contains a dot where only digits follow, the content cannot be transcluded.

For instance "Xyz 1.1" cannot be transcluded, but "Xyz 1.x1" or "Xyz 1.1x" can be transcluded.

PDAC-679 Artificial URL Properties not available in Properties Table Bug Major Done Fixed

The artificial properties that references URLs are not available during the rendering of the properties within the Document Properties Marker Macro (or the supplier macro).

This is because the URL values are derived from the document after the regular properties have been rendered.

PDAC-677 Boxing Issue with Text in div Element Bug Major Done Fixed

If the content of a div element having a class attribute value of "content-wrapper" is text, the unboxing will not remove the div.

We want the div element containing the class attribute to be always removed.

PDAC-675 Replacement fails in Transclusion if ID contains Umlauts Bug Major Done Fixed

Replacement fails if placeholder contains characters that are translated to HTML-Entities.

This is only evident if the content is moved to another section level.

PDAC-673 Rendering Properties Table in Definition List and Printer Mode Bug Major Done Fixed

If the Document Properties Marker Macro is set to definition list, in printer render mode the rendering is broken.

Parts of the CSS classes are rendered as text. The end of the tag seems to be determined wrongly.

PDAC-666 Duplicate Spaces shown in Space List Macro Bug Major Done Fixed

The space list macro lists spaces that match multiple categories multiple times. Each space should be listed only once.

PDAC-662 Exact Match Queries only work on projectdoc Documents Bug Major Done Fixed

Exact queries should work on all pages.

If you use a query like $<Tags>=[Xxx] then Lucene is complaining about the syntax iff the page is not a projectdoc document.

PDAC-661 Render Authors as String in Quote Macro Bug Major Done Fixed

If authors are rendered as a list and not as a list of comma-separated-values, the quote macro renders the names of the authors also as a list.

If the authors are stored in a list, the authors should also be rendered as a list of comma-separated-values.

PDAC-334 Page Preview does not work Bug Major Done Duplicate

The preview shows the information from the last saved page.

PDAC-700 Broken Blueprint and Space Blueprint Icons for IE and Firefox Bug Minor (migrated) Done Fixed

The blueprint icon for projectdoc Blank Document, projectdoc Demonstration Space and projectdoc Starter Space are not displayed for IE and Firefox.

PDAC-688 Remove Sort-By from the Name List Body Macro Bug Minor (migrated) Done Fixed

The sort-by parameter is shown although it has no effect. It should be removed.

PDAC-687 Version URLs of Change Log Macro Bug Minor (migrated) Done Fixed

The URLs to the versions rendered in the change log macro are null. Sometimes they point to the wrong resource.

PDAC-669 Add missing docs for Identifier Property in Transclusion Macro Bug Minor (migrated) Done Fixed

The transclusion macro provides the Identifier property which lacks documentation. The identifier is used to render an HTML identifier.

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.