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.
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.
- 1 New and Noteworthy
- 1.1 Delegate Documents
- 1.2 HTML Metadata for SEO
- 1.3 Support for Glossaries
- 1.4 Title Encodings
- 1.5 Spaces
- 1.5.1 Space Closures
- 1.5.2 New Space Properties
- 1.6 Required Document Properties
- 1.7 New Artificial Properties
- 1.8 New Property Controls
- 1.9 HTML Span Macro
- 1.10 Render Children in Table
- 1.11 Non-projectdoc Documents
- 2 Breaking Changes
- 3 Experimental Features
- 3.1 Changelog Macro
- 4 Known Issues
- 5 List of Changes
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.
@all, !TESTSPACEA, !TESTSPACEB
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.
@all, !#test
#test, !TESTSPACEA
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.
See Date Representation for details on provided artificial properties for the creation and last modification date.
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 metadata. | |
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:
Doctype Add-on | Compatible Version |
---|---|
Core Doctypes | 5.0 5.1 (recommended) |
Software Development Doctypes | 5.0 |
projectdoc Add-on for arc42 | 3.0 |
Doctypes for Agile Planning | 4.0 |
projectdoc Developer Diaries | 3.0 |
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 Name | Description | Example |
---|---|---|
Creation Date | The date in a date picker representation. | |
Creation Date Timestamp | The 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 Timestamp | The 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
Use the Display All Document Properties Macro to list all properties provided by a document.
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.
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 |
|
|
Done | Fixed |
Add reference to a delegate document to transclude document properties and document sections. |
PDAC-613 | Add Changelog Macro |
|
|
Done | Fixed |
Add a macro to render a table with selected change information for a document. |
PDAC-595 | Local Search Spaces |
|
|
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 |
|
|
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 |
|
|
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 |
|
|
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 |
|
|
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 |
|
|
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 Also add the normalized version for CREATION DATE and LAST MODIFICATION DATE. |
PDAC-609 | Add Document/Record Selection Macro |
|
![]() |
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 |
|
![]() |
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 |
|
![]() |
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 |
|
![]() |
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 |
|
![]() |
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 |
|
![]() |
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 |
|
![]() |
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 |
|
![]() |
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 |
|
![]() |
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 |
|
![]() |
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 |
|
![]() |
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 |
|
![]() |
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 |
|
![]() |
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 |
|
![]() |
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 |
|
![]() |
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 |
|
![]() |
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 |
|
![]() |
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 |
|
![]() |
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 |
|
![]() |
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 |
|
![]() |
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 |
|
![]() |
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 |
|
![]() |
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 |
|
![]() |
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 |
|
![]() |
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 |
|
|
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 |
|
|
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 |
|
|
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 |
|
|
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 |
|
|
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 |
|
|
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 |
|
|
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 |
|
|
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 |
|
|
Done | Fixed |
The documentation has not been updated. The key elements are separated by '.' not '-'. |
PDAC-569 | Links are not recognized as Content |
|
|
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 |
|
![]() |
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 |
|
![]() |
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 |
|
![]() |
Done | Fixed |
The Transclusion Macro fails to render a transclusion on a blog page. |
PDAC-610 | Cannot find referenced document: null |
|
![]() |
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 |
|
![]() |
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 |
|
![]() |
Done | Fixed |
The Display All Document Properties Macro cannot render content / page properties. |
PDAC-598 | Error Message for missing Transclusion Content not shown |
|
![]() |
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 |
|
![]() |
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 |
|
![]() |
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 |
|
![]() |
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 |
|
![]() |
Done | Fixed |
EAP versions of Confluence are not parsed by VersionHelper. |
PDAC-571 | Heading not rendered for Display List Macro |
|
![]() |
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 |
|
![]() |
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 |
|
![]() |
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 |
|
![]() |
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 |
|
![]() |
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 |
|
|
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.