projectdoc Toolbox

Space properties are defined for spaces and are accessed via the Space Property Macro. This tip goes into detail in how to use space properties with inheritence and extension pages.

Parent
Audience
Level of Experience
Expected Duration
30 min
Tags
Type

Organizing spaces often implies some variation by using a centralized configuration of variables. The projectdoc Toolbox implements these variables as space properties.

Space properties are properties defined on the space home page within the Document Properties Marker Macro. Multiple macros of the projectdoc Toolbox take advantage of this space-local configuration option.

This tip introduces the concept of space properties and provides links to further resources for advanced usage scenarios.

Contents

Basic Usage

The basic usage scenarios are specifying space properties and displaying space properties.

Define Space Properties

To define a property for a space you need to have write-access to the space home page.

 Locate Space Home Page ...

Locating the Homepage

 

Users typically find the home page by clicking on the  space icon on the upper left side of a page.

In case your space uses a theme that hides the space icon, you will find the home page on the space overview page. Look for the cog icon to access the space configuration pages and then click 'Overview'.

On the Space Details tab there is the reference to the home page of the space.

Open the space home page in the editor and add your properties to the table of the Document Properties Marker Macro.

Add a property per table row. The first column is the name of the property, the second column holds the value for the property. In the third column you find controls for the property. There are special controls for space properties.

 
  1. Space keys are required to be text-only. If there is additional markup your keys will not be recognized. Please refer to Cannot access Property from a Document for more information on this topic.
  2. Please note that not all space properties defined by projectdoc are resolving the values. Check the description of the space properties for details.
  3. Since version 1.11 of the projectdoc Toolbox users may use space property references to reference space properties within the table of the Document Properties Marker Macro more easily. Prior to this version use the Display Space Property Macro.

Use Space Properties

To reference a space property use the Display Space Property Macro.

 

We refer to the Display Space Property Macro, not the Display Space Attribute Macro, which is also part of the projectdoc Toolbox. While the first accesses properties defined with the Document Properties Marker Macro the latter references attributes defined by Confluence.

Using the macro is very simple: Type the name of the space property you want to display and you are done.

Leave the space parameter empty to refer to the current space. This allows to copy a page to a new space and automatically reference properties of the new space.

You may not only reference text, but also images. In the example above the value of the space property Logo is an image. Render the logo just like this:

Document Properties vs. Space Properties

 

Properties for documents and properties for spaces are both defined with the Document Properties Marker Macro. The only difference is the location of the macro. If it is on a space home page then these properties are accessible as space properties. You may also access the properties as document properties of the home page by using the display document properties macros. The only difference is that the document property macros require you to specify the document to access properties from.

Name Short Description
Renders a template with property references.
Renders the value of a document property as an image. The property value is required to an URL that points to an image.
Renders the value of a property of a document.
Displays a single property of a document that is referred by a property of another document and concatenates it with the value of a local property.
Displays a document property from a referenced document.
Renders a predefined list of documents in a table.

All Properties

Authors might want to peek into all available space properties from a given page.

Use the Display All Space Properties Macro to list all space properties. This is especially helpful if you inherit properties from other spaces (see Advanced Features).

Advanced Features

For more complex documentation scenarios, projectdoc provides a number of advanced features.

Inherit Properties from Spaces

projectdoc allows you to set spaces in hierarchies using the delegate-space property, which is a space property. Any properties defined in delegate spaces are automatically visible in the delegating space.

Please refer to Space Hierarchies for more information on this topic.

Organize Properties by Extension Documents

The number of space properties may be rising with time. To manage large amounts of space properties you may group them semantically and store them on separate pages.

Use the space property space-properties-extension to list pages that provide additional space properties as a space property on your space home page.

User-specific Settings

Properties specified within the properties table of the Document Properties Marker Macro on the home page of the user are also taken into account when rendering space properties.

These properties are used to define user-specific home pages for document types or allow users to switch roles.

 

Using user space properties may cause confusion within a team. One team member may have set a property another team member has not and therefore they get different renderings of a page. The reason for the difference is often not instantly obvious. Compare the properties for each user with the Display All Space Properties to see the differences in the configuration. The macro also shows where a particular space property is defined.

Use Space Property Controls to limit the export of space properties.

Templating with Space Properties

Template authors may want to display certain content only if a given space property is set. The Content Marker Macro allows to specify space properties that need to be set to show the content. 

This option is also available for sections.

Use Cases

Here are a couple of use cases that employ space properties.

Maven Projects

With projectdoc you may create spaces for software projects built with Maven. Create a space by reading the project's POM file. The properties of the POM are automatically made available as space properties.

Depending on the version of the product, different space properties may be enforced by using space properties extensions.

 

The doctype add-on is not yet available on the Atlassian Marketplace. Large POM files take a long time to create the space. While developers may deal with this, other users may be annoyed by the import process.

Until this problem is fixed users may choose to fork and build the add-on on their own. It is available on Bitbucket!

For more information on documenting projects built with Maven, please refer to:

Using projectdoc to document Maven Plugins
We decided to move our documentation from the XDoc format to projectdoc on Confluence. This allows us to update the information independent of the release cycles of the products. Here are some tips on how to use projectdoc for this task.
projectdoc for Maven Developers
A collection of blueprints for Confluence to create and work with documentation for Maven projects.
Maven Extension
Add-on to extend projectdoc for Confluence with Maven Tools.

Being a Pretender

Sometimes an author needs to look at a page as if she is a reader. For these use cases there is the pretend-being-a property that is only allowed to be specified as a user space property.

User-specific Home Pages

Users may want to define home pages for certain types of documents individually. It is also possible to store documents of a given subject automatically to a specific page.

The example shows how to set the home page for all Resource documents to 'Library' and direct all documents with the Subject 'Team Announcement' to the 'Announcements' page.

For more information on this topic, please refer to:

projectdoc.doctype.(doctype).home
Controls the location of the homepage of a given document type. Use the identifier of the doctype.
projectdoc.subject.(subject-name).home
A space property to control the location of the homepage of a given subject. Use the name of the subject to define the space property name. The value is a link to the page to store documents associated with the specified subject. Only available for versions prior to 2.0.
Home and Index Pages
Home and index pages help to organize documents by type. For each doctype there is a homepage and and index page. The homepage shows the central documents that are added to it (immediate children). Index pages list all documents of the space, regardless of their location.

Macro Configuration

A number of macros in the projectdoc Toolbox refer to space properties for a central configuration.

Here are two examples:

Remote Information Systems

Space properties allow to specify URLs to remote information systems to be used by macros of the Information Systems Extension. If the URL to such an information system changes, the URL needs to be edited only in one place.

# Name Status Short Description
1
Production
Renders an image generated from an Enterprise Architect diagram, transcluded from a server.
2
Production
Transclude HTML content from a remote server.
3
Deprecated
4
Production
5
Production
6
Deprecated
7
Deprecated
8
Deprecated
9
Deprecated
Transcludes a snippet from a project on a Subversion (SVN) server.
10
Production
Renders an image transcluded from a remote server.
11
Production
12
Production
Transclude content from a resource from a remote system.
13
Production
Transclude text content from a remote server.

 

Prior to version 1.11 of the projectdoc Toolbox these macros where part of the add-on. We decided to move them to an extension add-on since they are not required by all users. The extension is available for free, but needs the commercial projectdoc Toolbox Add-on installed.

Rendering Configuration

The Code Block Placeholder Macro takes advantage of space properties. You may for example define a default language with the code-language property.

Resources

Space Resources

Find more information on using spaces with projectdoc here:

Name Short Description Type
projectdoc introduces structure on a Confluence space. It adds the concept of homepages for document types.
projectdoc allows to group spaces and to set them in two kinds of relationships: delegate and search.
Learn how to access projectdoc space properties via REST API with cURL.
Renders all properties referenced by the current space.
Renders a space attribute value.
Renders a space property value.
Renders spaces with their attributes in a table or list.
Lists the configuration options at space level.
Links to documents that contain additional space properties. The order of the references to documents is important. The first location a value for a property is found, defines the value to the property. Later reference cannot override that value.
property
Lists valid controls for properties to be used as space properties.
Provides a gentle introduction to the concept of spaces using projectdoc.

Get Started

To get started with the projectdoc Toolbox have a look at the following resources:

Name Short Description
Provides information to get new users of projectdoc get started with projectdoc documents and spaces.
Get started with the projectdoc Toolbox: learning by doing
Concepts central to projectdoc. Things users have to understand to get the most out of using projectdoc.
projectdoc on the Atlassian MarketplaceInstall the projectdoc Toolbox and doctype add-ons via the Atlassian Marketplace.