- Created by Robert Reiner, last modified on 22. Nov 2024
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.
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.
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:
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.
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. |
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.
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.
Resources
- Release Notes Archive
- FAQs