Transclusion Cache, Report Support, Enhancements and Bugfixes, Support for Confluence 6.9
Today we released version 1.9 of the projectdoc Toolbox!
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.
The name changed from projectdoc to projectdoc Toolbox. We hope this will make it more clear to potential users that projectdoc is a set of tools to support project teams to create their modular and agile documentation collaboratively with their Confluence wiki.
New and Noteworthy
The following changes may be the most interesting of this release.
Transclusion Cache
For users that employ transclusion heavily, we added a transclusion cache that can be activated at space level. If you ask yourself "Am I using transclusions heavily?": If you have a few hundred documents that transclude documents transitively in depth 10, then yes, you'll take much advantage of this update.
Why didn't we activate for the whole instance per default? Caching always implies that you may have stale information. We provide a timestamp and an option to refresh the content for authors, but for typical usage scenarios where a document transcludes a multiple sections from a couple of documents usually does not call for caching.
With the help of the transclusion box authors will not only see transcluded content and jump to it by clicking on the name. The new version adds an extra edit button to open the document in an editor to apply changes quickly!
If you want to give it a try: Fragments Cache for Transclusions
Lucene Indexer
This version fixes some issues with the creation of the Lucene index and the document caches. After the Lucene indexer has finished, the document cache will now be cleared. Therefore there is no need to do this manually any longer.
Ancestor Searches
The doctype cache, which is required for the ancestor searches, did not always recognize when it has been cleared. As a result the queries selecting on ancestor properties has empty results.
With this release the cache checks on each access if a refresh is required.
Descriptive and Informative Abstracts
For teams creating documentation it is important to define the contents of the documents in advance. This is what the Description section on each document is for. Some documents need to distinguish between a description of the document and an informative summary of the content. The first is created in advance, the second after the document has been created.
We do not advice you to provide both sections for each of you documents. But lately it turned out for our documentation efforts that we sometimes need that informative summary and had no commonly defined space to put it. With this release most documents provide an additional space called Summary.
For more information on sections common to most document types, please refer to Document Sections.
Transclusion Recursion Detector
Due to the focus on reuse with transclusion and the possibility to specify queries to transclude from documents in the result set, it has become more and more important to detect recursions in the transclusion chain. With this release we added support for such a detection mechanism.
Breaking Changes
The following changes are incompatible with the previous release.
Default for Exclude-Self
The Display Table and Display List Macro now have the document the macro is part of excluded from the result set per default.
In previous versions the default for 'Exclude Self' has been 'false
'.
The reason for this change: The exclusion is the common case. Having the document launching the query included in the result set is rarely required.
Known Issues
This release has the following issues.
Blueprint Icons
The blueprint icons are not properly rendered in the Internet Explorer. Instead of the icon there is either the broken image link or no image at all.
There is an issue that tracks this problem
PDAC-561
-
Display Blueprint and Space Blueprint Icons in IE and Edge
Done
Upgrade Instructions
he following topics have to be considered for an upgrade to this version.
Compatible Doctype Add-on
Please note that we recommend to also update your free blueprint add-ons. Some of the add-ons also add new features or enhancements, but all have been tested to work with the projectdoc add-on in version 1.9.
Please check to update the following doctype add-ons:
- Core Blueprints (Release Notes)
- Blueprints for Software Development
- Blueprints for arc42
- Blueprints for Agile Planning
- Developer Diaries (Release Notes)
For those confused with the terms doctypes and blueprints: Blueprints are the implementation of projectdoc doctypes. A doctype defines the properties and sections of a document type.
There is no difference if you are referring to the Confluence context. But remember: For these add-ons' blueprints to work, you need to have the projectdoc Toolbox installed!
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 | Description |
---|---|---|---|---|
PDAC-527 | Cache for Transclusions |
|
|
Modular documentation employs transclusions quite heavily. While referencing content is an alternative, readers enjoy a compiled document more. Therefore we need to provide means to enhance the speed of calculating a page that is heavily using transclusions. One approach to enhance speed is to introduce caches. This should be our first strategy to tackle this problem. |
PDAC-508 | Replace Placeholders on Wiki Link |
|
|
Allow to set placeholders to be replaced with space (and page) properties. Currently only a handful of @-marked placeholders are considered. Replace any placeholder defined with ${...}. This will also help to reference versioned documents. |
PDAC-558 | Exclude Self Default |
|
![]() |
The default for the Display Table and Display List Macro for excluding self in the result set should be "true". This makes it safer for users and also is the natural default case. |
PDAC-551 | Summary for Informative Abstracts |
|
![]() |
The description is a descriptive abstract to introduce the reader in the structure of the document. It is used to help readers to determine whether or not the document at hand is interesting for their problem or not. We also want a section to contain the informative abstract. Readers may read this summary and get all information of the document in a brief manner. Team could therefore define the structure of the document in the description and collect information in the summary. This will support collaboration. Not all document types need a summary. Categories, Tags, ... have descriptions and that is all they need. But each document with a topic-like intention should have a section called summary to host informative information. |
PDAC-530 | Refresh Document als kicks out Fragments from Cache |
|
![]() |
When the user invalidates an entry in the document cache, it should also be invalidated in the page fragments cache. |
PDAC-529 | Render last Update Timestamp on Transclusion Box |
|
![]() |
To make the last update of a transcluded fragment visible to authors, render the timestamp of the last update on the box around the transcluded content. |
PDAC-528 | Allow Transclusion Macro to switch off Cache |
|
![]() |
Allow the author to decide per transclusion if the cache should be used to lookup page fragments or not. The switch only controls the behavior of the macro, not that of macros' content that is transcluded transitively. |
PDAC-525 | Add Space Description Box for Space Creation Wizard |
|
![]() |
Allow to add a space description on creating a space with a wizard. |
PDAC-510 | Add Buildmetadata as Metadata |
|
![]() |
Buildmetadata created with the Buildmetadata Maven Plugin should be made available as metadata. Currently we do not need to have a human readable report, just the metadata to reference. Each buildmetadata property name is prefixed by "buildmetadata.". It is the linearisation of the XML document that is stored inside the "JAR/META-INF/buildmetadata.xml". The properties file is not used (since the other keys are generated). |
PDAC-507 | Store Version Document in Blueprint Context |
|
![]() |
For later reference store the version document instance in the blueprint context by the key "projectdoc.pages.version". This will allow report generators to attach themselves to that version. |
PDAC-506 | Report Page Generation |
|
![]() |
Add support to add report pages. It should be easier to add information from external sources. |
PDAC-519 | Allow to select the Icon for the Space List |
|
|
Allow to select the icon to be rendered as in a column of the space list rendered by the Space List Macro. |
PDAC-554 | Provide icons for refresh and edit links in transclusion boxes |
|
|
Transclusions can render boxes around the transcluded content. These boxes provide a link to edit and refresh the transcluded content. These links shall be replaced by icons provided by Confluence AUI. |
PDAC-553 | Parent Macro Support for Ancestor Search |
|
|
Like the Name List Macros the Parent Property Macro should also support ancestor searches. |
PDAC-546 | Detect Transclusion Recursion |
|
|
If transclusion enters recursion the systems gets under heavy load until the stackoverflow is reached. We should detect this situation and stop transcluding once we reach a document we transcluded from before. |
PDAC-526 | Streamline Transclusion Semantics |
|
|
The semantics of transclusions should be improved to:
|
PDAC-504 | Support Import of Maven BOM |
|
|
Import of Maven projects that use BOMs fail. |
PDAC-557 | Guard Create-Buttons with Hide Macro |
|
![]() |
All Create-Buttons have to be hidden if the user has only reading privileges. Some templates already have this guard, but now we want all templates to provide it. |
PDAC-555 | Handle Sections with PDF Attachements as non-empty |
|
![]() |
Rendering attachments (e.g. PDF) in a section will render them as empty. They should be recognized as non-empty. |
PDAC-552 | Render Date with the Quote Macro |
|
![]() |
The Quote Macro renders the "Publication Date" property of a document instance. If this is not specified, it should render a generic "Date" property. |
PDAC-543 | Dismiss non existing Section gracefully |
|
![]() |
If the Document Properties Marker Macro delegates to document that lacks certain sections, we should not render an error box, but instead should render nothing. If the user wants to be strict (and render a box on a missing section), she has to configure this behaviour via a space property. |
PDAC-541 | Not overriding Blank Document Properties |
|
![]() |
The document properties on the blank template should not override the standard settings of the space. |
PDAC-537 | Suppress Transclusion Box around Properties Table |
|
![]() |
If the user decides to select properties to be rendered in a table above the transcluded sections with the Transclude Documents Macro, the table is enclosed in a transclusion box. Since the whole hit is already rendered in such a box, the box is rendered twice. It should be rendered only once. |
PDAC-534 | Rename Blank Space to Starter Space |
|
![]() |
'Blank Space' is misleading. We provide this space blueprint to get new users start with projectdoc quickly. The main aspect of the space is that it does not assume that users employ any document types (not even the core doctypes!). Therefore the Tags and Categories properties do not assume the use of the Tag and Category doctype and do not render a Name List Macro. We should get this message more clear on the Space and Page Blueprint and rename the Space to 'Starter Space'. The name 'Blank Page' seems good enough. It is basically a blank page in the sense of projectdoc. If users would use the Core Doctypes they would use the Generic Doctype which integrates with the other Core Doctypes (e.g. Role, Tag, and Category). |
PDAC-533 | Allow to render Tour Table without Header |
|
![]() |
Add a parameter to suppress the table header rendered by the Tour Macro. |
PDAC-531 | Allow to render Display Table without Header |
|
![]() |
Add a parameter to suppress the table header. |
PDAC-517 | Default Template for Display Properties Macro |
|
![]() |
To make it easier to use the Display Properties Macro the mandatory Template property is now optional. If not specified, it now defaults to $[Name] - ${Short Description}
If this does not meet the user's requirements, it can be easily changed (as always). |
PDAC-513 | Refresh Creates Page Tree |
|
![]() |
As a workaround run a refresh on the generated page tree whenever we create one. It seems that the API we generate page by page does not work as expected. Sometimes we do not get properly created pages. At least they seem to pass the Lucene Indexer to late. We should check if we could alter the use case to get a more performant solution. |
PDAC-509 | Allow Wrapping Content Marker Macro |
|
![]() |
Unfortunately the body is extended to create valid HTML. This makes it difficult to render HTML fragments. Therefore add a new property to the Content Marker Macro to wrap the content by another element. This is especially useful to add list elements. |
PDAC-505 | Section with Media Content |
|
![]() |
If the Section Macro contains media content, it does not render. This is because it regards the iframes used by Confluence to render media as empty. We should check for iframes and assume that they are not empty to render sections that contain only a reference (via an iframe) to media content. |
PDAC-503 | On failed POM Import provide Error Message on Homepage |
|
![]() |
The problems encountered on importing a POM are currently only logged to the Confluence log file. We should add this to the homepage to inform the user who run the import immediately. |
PDAC-502 | Document Type Conversion Sort Order |
|
![]() |
Add documentation to the Sort By Property of Display Table, Display List, and Transclude Documents Macro. The Type Conversion feature is not obvious. |
PDAC-501 | Render Content Marker Macro Span only with Content |
|
![]() |
Render the span element of the Content Marker Marco only, if there is content. Also suppress the identifier if it is not specified. |
PDAC-500 | Enhance Error Report on Missing Nexus Configuration |
|
![]() |
The message of the Nexus Link Macro for signalling errors to the user is rather brief. We should add a link to the documentation to help users finding out what to do more quickly. |
PDAC-499 | Use Download URL of Distribution Management |
|
![]() |
Currently we try to derive the artifact repository URL from the release or snapshot repository of the distribution management of the POM. But the information we should use is the download URL. https://maven.apache.org/pom.html#Distribution_Management |
PDAC-550 | Add Spacekey to Tooltip in Transclusion Box |
|
|
Add spacekey to tooltip in link of transclusion box to transcluded page. |
PDAC-532 | Render Header of Display Table |
|
|
The header rendered by the Display Table Macro should render inside a HTML thead element. |
PDAC-540 | Refresh Tree Action Fails |
|
|
On starting the tree refresh action the browser reports a content encoding problem. |
PDAC-547 | Overriding of Field "Render As" in Document Properties Marker Macro does not work |
|
|
When via Space Property or via an Index Space (Delegat Space) the Space Property render-metadata-as is set to "definition-list" it can not be overwritten via "Overwrite Checkbox" in the Document Properties Marker Macro. |
PDAC-544 | Transclusion resolves CDATA Blocks |
|
|
Transclusion parsed the content and thereby translates CDATA content to text. See https://github.com/jhy/jsoup/issues/406. We have to preserve the CDATA block otherwise the code macro will not render the content correctly. |
PDAC-539 | Lucene Indexer fails to create projectdoc Document Cache |
|
|
If the projectdoc Document is created with the indexer, not all properties are rendered properly. If the page tree is refreshed, this problem does not occur. If the page is saved and the indexer runs, the problem does not occur. |
PDAC-538 | Doctype Cache gets lost |
|
|
The cache that stores the doctype information gets lost. This is okay, since it is a cache, but currently it is not able to refill itself. The consequence is that ancestor searches (those based on the type of a property) will not work. The failure is an empty result set. In any situation that invalidates the cache or its contents (low memory, restarts, redeployments, ...) the cache is required to get back to a valid state. |
PDAC-524 | Space Property 'suppress-transclusion' fails |
|
|
Setting the space property 'suppress-transclusion' to 'true' does currently not suppress transclusions. |
PDAC-560 | Unable to Escape Characters in Query |
|
![]() |
If a value to query for in an exact match query contains a special character (e.g. a bracket), the query parser is unable to parse the input string successfully. The problem is that the user has to have the option to escape characters that have to be taken verbatim. The parser cannot, without any help, examine the input string and detect which spacial characters are taken as is and which have special meaning. We therefore need the feature of escaping characters. For instance: To find a document with an exact match containing brackets, the query looks like this: $<Identifier>=[My Term (with brackets)] |
PDAC-559 | Remove Exclude Self for Transclude Documents Macro |
|
![]() |
The Transclude Documents Macro does not allow to change the settings for exclude self for security reasons. Therefore the checkbox has to be removed from the macro configuration page. |
PDAC-556 | Getting Started Link broken |
|
![]() |
The information for new users to get started with projectdoc has a link that points to a non-existing page. It should link to www.smartics.eu/confluence/display/PDAC1/projectdoc+for+Confluence+V1 |
PDAC-549 | Space Delegate Calculation broken |
|
![]() |
The calculation of the delegate spaces is broken. The parent space (if not per incidence is the index space) is not taken into account. |
PDAC-548 | Display Table Macros Counter Column Conflicts With Calculation Columns Feature |
|
![]() |
Activating the Counter Column in a Display Table Macro and using the Calculate Columns feature leads to a corrupt rendering of the table. |
PDAC-536 | Transclusion of Raw Text |
|
![]() |
The transclusion macros do not transclude text outside of HTML elements. This is especially true of the content of the Section Macro is raw text. |
PDAC-535 | Definition List Renders illegal Names |
|
![]() |
The display list renders the normalized original value instead of the normalized rendered value. |
PDAC-523 | First selected Property is rendered as Title |
|
![]() |
Using the Transclude Documents Macro and using the Select Property, the first selected property is always rendered as section title. Instead it should either check the status if the "Name as Heading" property and understand if a title is rendered with the Ids/Tags selection. If this is the case the table with properties should be rendered after the section heading but before the sections. |
PDAC-521 | "Name as Heading" renders Heading twice |
|
![]() |
Setting the "Name as Heading" property of the Transclude Documents Macro will render the title of the document as heading twice, if there are properties selected. The Select property contains "Name, Iteration". No Ids or Tags selected. The rendering of the second heading should check if a heading is already rendered and suppress the duplicate rendering. In addition to that the level of the transcluded sections have to be increased by one level if the heading is rendered in front of the properties table. |
PDAC-520 | Selected Heading rendered with Numbering |
|
![]() |
A user selects properties to be displayed in a table with the Transclude Documents Macro. The user selects name and iteration so that the name is rendered as a heading at a selected level. Then the heading is rendered with a number even if no numbering is selected. Expected is that the heading is not rendered with a number. |
PDAC-518 | Restricted Link in Tour Macro |
|
![]() |
If the tour macro contains a link to a page the user has not access to, the whole table is not rendered. Instead only the links to the page without access permissions should be skipped. |
PDAC-516 | User Space must not override all Properties |
|
![]() |
Since user space properties are preferred they will also apply for information (such as space key or creation time) where they should not. |
PDAC-514 | Create-Template Buttons not removed |
|
![]() |
The remove-Create-Template-Button feature does not remove the element any longer. This problem applies to the latest Confluence version (5.8.9). |
PDAC-512 | SNAPSHOT Access |
|
![]() |
Snapshot artifacts cannot be downloaded from remote repositories. The resolver does not cope with tagged snapshot versions. Therefore we have to tell the subsystem that the versions are not unique. |
PDAC-545 | Stacked box macros are rendered with wrong images |
|
|
When box macros are stacked the inner boxes are rendered with wrong images. |
PDAC-522 | Short Description rendered before Title |
|
|
Using the Transclude Documents Macro and selecting "Extract Short Description" will render the short description in front of the section title. I would expect that it is shown after the title and before any other content. Are there use cases that expect the short description in front of the title? |
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.