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.
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.
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.
- 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.
- Please note that not all space properties defined by projectdoc are resolving the values. Check the description of the space properties for details.
- 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 |
|---|---|
| Display Document Properties Macro | Renders a template with property references. |
| Display Document Property As Image Macro | Renders the value of a document property as an image. The property value is required to an URL that points to an image. |
| Display Document Property As Link Macro | Renders the value of a document property as a link with an alternative label. |
| Display Document Property As List Macro | Renders the list value of a document property. |
| Display Document Property Macro | Renders the value of a property of a document. |
| Display Document Property Ref Concat Macro | 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. |
| Display Document Property Ref Macro | Displays a document property from a referenced document. |
| Tour Macro | Renders a predefined list of documents in a table. |
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.
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:
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:
