projectdoc Toolbox

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. 

Contents

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 Spaces, except Test Space A & B
@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.

 
Exclude Spaces labelled with 'test'
@all, !#test
List Test Spaces, but not Test Space A
#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 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
 

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.

Key Summary T P Status Resolution Description
Loading...
Refresh

Resources

  • Release Notes Archive
  • FAQs