projectdoc Toolbox 1.10 Release Notes

Delegate Document Feature, SEO Support, Glossary Support, Title Encodings, Space Closures, Date Properties

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

New and Noteworthy

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

Delegate Documents

If you ever thought of extending a document without touching it, the delegate document feature is for you! If you have a document for a person and you want to add additional information to that document in another space you now simply create that new document and delegate to the existing one. Each section of your new document will now render the section of the delegate document as long as it is empty.

To use this feature add a reference to the delegate document to your Document Properties Marker Macro. Read about how delegation works with the Section Macro and delegation for document properties.

HTML Metadata for SEO

The properties of a document can be exported as metadata on an HTML page easily. This metadata such as keywords or DC.description is used by web crawlers or search engines to enhance user experience or the search rank ratings.

For more information on this topic refer to Export Metadata on how to configure this feature and Metadata Sets for example sets.

Support for Glossaries

This version adds new macros to make working with glossaries and other indices easier.

Index Card Macro
Renders transcluded content fetched from documents of a result set.
Index Entries Table Macro
Renders a table of index entries.

Title Encodings

Title encodings work around the problem that the title of a Confluence page has to be unique within a space. The encodings are defined by the template author and should be activated by default.

This version introduces the encodings for the following types:

Type Short Description Encoding
Categories allow to set document instance of different doctypes in a hierarchy.
Document the semantics of a tag. May also be used to document Confluence labels.
A party that takes interest in a project. The stakeholder is either a real person, an organization or group, or represents a class of individuals, groups or organizations.
Subject documents allow to set document instance of different doctypes in a common context.

Spaces

Space Closures

A space may have defined a list of spaces as its search space. Search macros use the search space to collect documents for the result set. The @all is a special token to search in all spaces. From this version on we also allow to exclude spaces from the search.

Authors may also use space labels to include or exclude a set of spaces attached to this label. Use the ' # ' to select spaces by a space label.

New Space Properties

The following space properties has been introduced with this version.

Name Short Description
List of spaces to include in downstream searches to be used for the defining space only. Use @all to refer to all spaces.
Controls to render sets of metadata based on document properties.

Required Document Properties

Sections and content may be hidden dependent on the presence of a property in the document.

This is an interesting feature especially for template authors to design blueprint that hide document parts not relevant in a given context.

New Artificial Properties

Artificial properties are properties that are automatically added to projectdoc documents and available to be selected, used as constraints, or for sorting.

Dates

Sorting by dates is now easier by using normalized date values to be used with Lucene searches. If the property value is specified with the Confluence Date Autocompletion (opened with the shortcut ' // '), and for the creation and last modification date, a normalized date is provided as an artificial property.

The name of this artificial property is that of the original property plus the § -sign appended.

Here is an example where the creation date is check against a custom property named Last Update.

$[Creation Date§]: [${Last Update§} TO NOW]

There is also an artificial property value containing the date as a timestamp in milliseconds, prefixed with zeros up to 19 digits ( %019d ). The name of the artificial property is constructed from the original name plus the suffix Timestamp (separated by a blank). Note that the Creation Timestamp is the creation date in milliseconds, while the Creation Date Timestamp is the representation of the date (without hours, minutes, seconds) in milliseconds.

The change may break sort orders for instance in the Display Table Macro where the use of

Creation Date@{date}

attempts to parse the date in the user's default format. With this version use Creation Date§ instead.

Index Key

The Index Key is helpful to define glossaries. Authors may sort the hits of a Display Table Macro using the index key and name.

The index key is typically the first character of the name. It may be defined by the author as a document property within the Document Properties Marker Macro to override the default.

Since the value may be overridden the index key is technically a special form of an artificial property.

New Property Controls

This version includes the following new property controls.

Name Short Description
Signals that the property should be transcluded from the delegate document.
Exports the property as schema information.
The property must not be seen outside the space. This is typically used for properties defined in the personal space that should not be used outside this space. Note that specifying this control will hide the property imported from delegate spaces.

HTML Span Macro

The new HTML Span Macro allows to attach a CSS class to a span. This makes it much easier to render Confluence icons.

<span class="aui-icon aui-icon-small aui-iconfont-devtools-arrow-right"> Insert meaningful text here for accessibility</span> 

Render Children in Table

The Display Table Macro now allows to render the children of a search hit. This is helpful for authors who want to render a hierarchical view on documents that meet a given search criteria.

Non-projectdoc Documents

This version improves support of macros used on non-projectdoc documents. Previous versions typically assumed to calculate default values for non-projectdoc documents. With this release macros will distinguish between projectdoc documents and simple Confluence pages. This removes problems on updating pages that have been converted to projectdoc documents.

Breaking Changes

The following changes are incompatible with the previous release.

Remove projectdoc Label

Before 1.10 projectdoc relied on the ' projectdoc ' label to mark pages that are projectdoc documents. With this version this visible tag is removed and replaced with a content property. The inner workings will then check the content property instead of the tag.

For migration we will always check the content property first and then the label to determine if a page is a projectdoc document. If the ' projectdoc ' label is removed we will automatically add the content property.

This is a breaking change for those use cases that expect that projectdoc documents will have a ' projectdoc ' label. For instance users who use the Content By Label Macro will not find new pages.

A side effect of this change is that pages with named doctypes, that is doctypes that are not based on a blueprint, will not have the name of the doctype as a label. This is - for instance - the case with docsections.

Users who do not use the ' projectdoc ' label for their work will not notice the change. Users who do should be aware of the fact that this label is no longer added automatically.

Doctype Add-on Update

With the update to the projectdoc Toolbox 1.10 the doctype add-ons need also be updated. This is due to an API change that will break compatibility of older versions of the add-ons.

Therefore please update your doctype add-ons to the following versions:

Date Representation

The creation and modification time of a page provided by Confluence is accessible by artificial properties. With this Version the names are as follows:

Property NameDescriptionExample
Creation DateThe date in a date picker representation.
 
Creation Date TimestampThe date (with day precision) with leading zeros in milliseconds.0000001456441200000
Creation Date$The date as text.26 Feb 2016
Creation Date§The normalized date with format yyyMMdd.20160226
Creation TimestampThe timestamp in milliseconds with leading zeros.0000001456510125056

The same representations are available for the last modification date:

  • Last Modification Date
  • Last Modification Date Timestamp
  • Last Modification Date$
  • Last Modification Date§
  • Last Modification Timestamp

Experimental Features

A feature tagged as experimental is currently tested. Use cases are explored and changes to the user interface are likely. We intend to get feedback from users to forge the final version of the feature.

Changelog Macro

The Changelog Macro is added as an experimental feature. The macro renders changes with their comments in a table.

Changes are tricky to track when users apply transclusion. Therefore the macro is helpful in a number of use cases and confusing in others. We release it and marked it as Experimental to learn more about how this macro can be improved.

Known Issues

This release has the following issues.

Content By Label Warnings

We use the Content By Label Macro on the homepages of spaces. We add a valid element that points to the space the macro include for its search. Due to changes to the macro, it is now migrating the information to CQL, setting the space as a string property. This will not break the macro, but the following message will be written to the Confluence log file:

Unhandled parameterType com.atlassian.confluence.content.render.xhtml.model.resource.identifiers.SpaceResourceIdentifier for macro contentbylabel with
            value of com.atlassian.confluence.content.render.xhtml.model.resource.identifiers.SpaceResourceIdentifier@143fc

If you need to remove this warning, just remove the Content By Label Macro from the space homepages generated by the free add-ons. Alternatively you may change the parameters of the macro to use the CQL, but this option depends on the version of your Confluence installation.

Viewing Glitch

In cases where the storing and indexing of the page takes longer than the following view rendering process the content of the rendered page may not be up-to-date. This is especially an issue for homepages on space creation.

The user has to reload the page to see the updated content.

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-511 Delegate Document New Feature Blocker (migrated) Done Fixed

Add reference to a delegate document to transclude document properties and document sections.

PDAC-613 Add Changelog Macro New Feature Critical (migrated) Done Fixed

Add a macro to render a table with selected change information for a document.

PDAC-595 Local Search Spaces New Feature Critical (migrated) Done Fixed

For index spaces the exported space (referencing attachment spaces) typically differs from the locally used search space.

Therefore we need to provide a search-space-local property that is only used locally.

PDAC-592 Index Entries Table Macro New Feature Critical (migrated) Done Fixed

Allow to render a table of glossary items more easily. Basically the doctype is predefined and the term names may be added to the macro body.

PDAC-590 Index Macro New Feature Critical (migrated) Done Fixed

Make it easier to select on documents to render a glossary. The terms to add should be added to the body of the macro and influence the query result.

PDAC-580 Support HTML Metadata New Feature Critical (migrated) Done Fixed

Make the information provided in the document properties available in the HTML metadata. Allow to export the information manually (with a property control named 'export') and allow to select a set where an automatic mapping is applied.

PDAC-568 Provide local Space Properties New Feature Critical (migrated) Done Fixed

We require a property control that prevents a property to be exported. This is especially necessary for personal space to prevent properties intended for local use from taking effect on other spaces.

PDAC-563 Artificial Properties for Dates New Feature Critical (migrated) Done Fixed

When a property value is specified with the Confluence Date Picker, we should add artificial properties for the plain, the timestamp, and the normalized value.

The normalized value will contain a date representation to be used with Lucene as in
$[Creation Date§]: [${Last Update§} TO NOW]

Also add the normalized version for CREATION DATE and LAST MODIFICATION DATE.

PDAC-609 Add Document/Record Selection Macro New Feature Major Done Fixed

Add a macro to make it visible to all team members which documents are expected to be maintained and which are just a record.

PDAC-608 Role List Macro New Feature Major Done Fixed

Add a macro to add the names of groups with view permissions to the list of role names.

PDAC-607 Add Sponsors as common Property New Feature Major Done Fixed

Introduce the sponsors as a property for templates. This makes it easier to define the stakeholders interested in a given document in a standardized way.

PDAC-602 Render Creation and Modification Date as Date Picker New Feature Major Done Fixed

To make the rendering of the creation and modification dates more appealing we should represent them in the date picker element.

PDAC-600 Add Artificial Property for Version History New Feature Major Done Fixed

Allow to query for changes to a document by introducing a new artificial property called 'VersionHistory'. The property value is a list of 'user:date' tokens that allows to use this information as a filter on queries.

PDAC-599 Transform Date Values to Date Picker New Feature Major Done Fixed

Allow wizards to transform a date value to a date picker.

Users select a date in a page wizard. The template author specifies properties to be transformed by the property 'projectdoc-adjustVarValues-toDatePicker'. All values associated with one of the specified date will be rendered as a time element that is rendered as a date picker.

PDAC-596 Support Rendering Parents as Delegate Document New Feature Major Done Fixed

Template authors may need to set a parent document as the delegate document for a new page. This requires to add an XML fragment. To add this, we introduce a flag to set to the soy template that will trigger the generation of the fragment and store it under the key 'projectdoc.xml.delegate-document.parent' in the context.

PDAC-588 Add Index Key as Artificial Property New Feature Major Done Fixed

To query for document instances by "Index Key" create an index key as artificial property.

The property is just the first letter of the name of the document.

It may be overridden by the author with a document property.

PDAC-583 Labels for Space Closures New Feature Major Done Fixed

Allow to select space keys by space labels.

The feature has to be supported by the query macros (Display Table) and name list macros.

PDAC-582 Exclusion for Space Closures New Feature Major Done Fixed

There are use cases where a user requires to exclude selected spaces from the closure of e.g. search spaces. In this case the user specifies "@all" and then selectively removes spaces by their name.

The feature has to be supported by the query macros (Display Table) and name list macros.

PDAC-575 Display List Macro: Select Property to Display New Feature Major Done Fixed

Allow to select the property in the list. The property defaults to the Name of the document.

PDAC-573 Support for Title Encodings New Feature Major Done Fixed

Title encodings work around the problem that the title of a Confluence page has to be unique within a space. The encodings are defined by the template author and should be activated by default. But it may make sense to allow the page author to switch it off.

In future versions we may add features to allow information architects to define the encodings as space properties.

PDAC-572 Support Short Names New Feature Major Done Fixed

Some doctypes have names that are unwieldy in the context of the doctype. For instance the name of a category contains the full path to the root of the category. In the context of the parent category we would like to refer to the category by its short name, sufficiently unique within its siblings (as defined by the category doctype).

We may later expand this feature with defaults between the name and the short description. For now we only need to introduce the concept by its unique key and translations.

PDAC-570 Transclusion Macro should support @self as Title to Reference the actual Page New Feature Major Done Fixed

As the tilte field is mandatory it can no longer be left empty so this usecase is no longer supported. By introducing @self this use case could be provided once more.

PDAC-567 HTML Span Macro New Feature Major Done Fixed

Add a macro to render simple HTML spans.

We need this feature to render Confluence symbols more easily.

Since we render plain HTML, we make this macro disabled per default.

PDAC-565 Required Document Properties New Feature Major Done Fixed

Allow to render sections or marked content only, if a specified property is available in this document.

This is similar to the required space properties parameter already provided by the Section Macro and the Content Marker Macro.

PDAC-418 Render Children of a Result Set with the Display List Macro New Feature Major Done Fixed

Allow to render the children of documents that match. The children will be rendered independent of the constraints in the query.

PDAC-612 projectdoc Document should not require Doctype Label Improvement Major Done Fixed

To define a projectdoc document the presence of the properties table should be sufficient. Currently it is required that the document has a label that matches the name of the doctype.

We need to check if queries suffer a performance impact.

PDAC-605 Handling of non-projectdoc Documents Improvement Major Done Fixed

Although a Confluence page is not a projectdoc document, projectdoc parses it and creates an instance. This should be prevented.

This leads to problems once the page is turned into a projectdoc document.

PDAC-587 Apply Column Alignment to Display Table Macro Improvement Major Done Fixed

Allow to define the alignment with the selected property names of the Display Table Macro.

PDAC-586 Apply Head Styles to Columns of Tour Macro Improvement Major Done Fixed

Adding an alignment style to the head cell of a table column should render all cells in this column with that style.

PDAC-585 Search and Delegate Space Property Values Improvement Major Done Fixed

Currently the space properties 'search-space' and 'delegate-space' are returned 'as-is'. We need to return the resolved value for these two properties (as long as they both are transitive closures).

PDAC-584 Allow Rendering of Space Closure Space Property Improvement Major Done Fixed

Currently the space properties 'search-space' and 'delegate-space' are required to be plain text. We need to allow to use macros to support complexer use cases.

PDAC-574 Change Rendering of Iteration Macro to Prepare Support for Scroll Office Improvement Major Done Fixed

The rendering of the iteration macro must be changed to support an easy Scroll-Office support.

PDAC-616 Move AO Access in Indexer to Persistence Layer Improvement Minor (migrated) Done Fixed

The indexer needs to read information from a projectdoc document to add searchable information. On accessing the page it may not yet exist and is therefore created. This code should be part of the persistence layer.

PDAC-615 Message on missing Document in Result Set Improvement Minor (migrated) Done Fixed

Once the result set is created the information to display for each hit is determined. If the page has been removed, a warning message is written to the log.

Since this is not a warning but an information for trouble shooting, it should be set to 'DEBUG'.

PDAC-578 Wiki Link: Render Space Ref Style Improvement Minor (migrated) Done Fixed

Allow to switch off rendering a CSS style to signal a link to a document in another space.

PDAC-577 Wiki Link: Enhance Link Rendering Style Improvement Minor (migrated) Done Fixed

Handle the strategy for rendering the link by a selection box instead of multiple exclusive checkboxes.

PDAC-576 Wiki Link: Render No Docs Style Improvement Minor (migrated) Done Fixed

Allow to switch of the rendering of a style class if index page for a given type are present.

PDAC-542 Allow to delegate to non-existing Properties Improvement Minor (migrated) Done Fixed

If the Document Properties Marker Macro delegates to a document, a property is marked as to 'delegate' (via control) and that property does not exist in the delegate document, a NPE is thrown.

The macro should be graceful with not existing properties.

PDAC-603 Space Creation Problem Bug Blocker (migrated) Done Fixed

Space creation fails with problems updating the projectdoc documents in the database. The log shows messages from Hibernate complaining about transactions to be rolled back.

PDAC-601 Remove projectdoc Label Bug Blocker (migrated) Done Fixed

Before 1.10 projectdoc relied on the 'projectdoc' label to mark pages that are projectdoc documents. We now want to remove this visible tag and replace it with a content property. The inner workings will then check the content property instead of the tag.

For migration we will always check the content property first and then the label to determine if a page is a projectdoc document. If the 'projectdoc' label is removed we will automatically add the content property.

This is a breaking change for those that expect that projectdoc documents will have a 'projectdoc' label. For instance users who use the content-by-label macro will not find new pages.

A side effect of this change is that pages with named doctypes, that is doctypes that are not based on a blueprint, will not have the name of the doctype as a label. This is - for instance - the case with the docsections.

PDAC-593 Default Homepage override fails Bug Critical (migrated) Done Fixed

The documentation has not been updated. The key elements are separated by '.' not '-'.

PDAC-569 Links are not recognized as Content Bug Critical (migrated) Done Fixed

A property value that contains a Confluence link is not recognized as having content. It should not be deemed as being empty.

PDAC-617 Remove projectdoc Document on Label Remove Bug Major Done Fixed

If the label from a projectdoc document is removed that is not a projectdoc document, the document is not removed from the persistent cache.

Should be fixed to remove the document on label remove of a projectdoc label.

PDAC-614 Block Rendering of Section Properties Bug Major Done Fixed

If a section is rendered as a property within a cell of a table that is rendered by the Tour Macro then this content is rendered as inline. This leads to a compact rendering of e.g. lists.

PDAC-611 Transclusion Macro on Blog Pages broken Bug Major Done Fixed

The Transclusion Macro fails to render a transclusion on a blog page.

PDAC-610 Cannot find referenced document: null Bug Major Done Fixed

On space creation the homepage is not in the Lucene index and therefore the Properties Document Marker Macro renders this error message:

Cannot find referenced document: null

Reloading the page replaces the error message with the properly rendered properties.

This also applies to Confluence pages that are converted to projectdoc documents.

PDAC-606 Removing projectdoc Marker not supported Bug Major Done Fixed

If a user removes the document properties marker macro, an existing content property or label (with name projectdoc) is not removed.

PDAC-604 Display All Document Properties fails on Content Properties Bug Major Done Fixed

The Display All Document Properties Macro cannot render content / page properties.
Instead of listing the properties, an error message is rendered.

PDAC-598 Error Message for missing Transclusion Content not shown Bug Major Done Fixed

The Transclusion Macro can be configured to render an error message if the transcluded content is empty. Currently the error message is only shown if the referenced document is not found. It should be also rendered if the ids and tags do not render content.

PDAC-594 Homepage Move fails to Update Parent Bug Major Done Fixed

When a new document is relocated to its doctype homepage (on creation), the document is stored at the correct location, but the ancestor information does not reflect this. The ancestor still points to the old location.

PDAC-591 Extract Short Description fails for Transclude Documents Macro Bug Major Done Fixed

Selecting 'Short Description' renders the property within the table successfully. But when 'Extract Short Description' is selected, the property is not rendered.

PDAC-581 Rendering Problem for Property Values Bug Major Done Fixed

Table cells that contain two property values that are rendered as boxes are larger than the box values in cells where there is only one value.

PDAC-579 Enhance VersionHelper to support EAP 6.X Versions Bug Major Done Fixed

EAP versions of Confluence are not parsed by VersionHelper.
E.g. 6.0.0-OD-2016.01.1-0006

PDAC-571 Heading not rendered for Display List Macro Bug Major Done Fixed

If the render mode of the Display Table Macro is set to section style, the heading is not rendered.

PDAC-566 Empty Required Space Properties Bug Major Done Fixed

Checking required space properties (Section and Content Marker Macro) assumes only blank values to be not existing. But Confluence easily adds a nbsp entity which we should also deem as being blank.

PDAC-564 Rendering broken for tabular Style Bug Major Done Fixed

The tabular style is broken. The elements following the list are flowing on the right side.

The content should be rendered below the list.

PDAC-562 Closing DIV and SPAN Elements are Misaligned Bug Major Done Fixed

In some Confluence versions (e.g. 5.5.X and 5.8.X but not 5.9.x) a HTML span-Element followed immediately by a closing HTML span-Element is misaligned such that its closing tag is deferred and is placed after the next HTML div block. This also occurred for a div-block.

PDAC-561 Display Blueprint and Space Blueprint Icons in IE and Edge Bug Major Done Fixed

Using IE or Edge as browser the projectdoc icons in the create and create new space dialog are not displayed.

PDAC-618 Fix Links in Demo Space Bug Minor (migrated) Done Fixed

Fix links on the homepage of the demo space.

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.