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: Tips
Audience: Author, Confluence Administrator, Template Author
Level of Experience: Advanced Beginner
Expected Duration: 30 min
Tags: Space
Type: Tip

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

1 Basic Usage
- 1.1 Define Space Properties
- 1.2 Use Space Properties
- 1.3 All Properties
2 Advanced Features
3 Use Cases
- 3.1 Being a Pretender
- 3.2 User-specific Home Pages
- 3.3 Macro Configuration
  - 3.3.1 Remote Information Systems
  - 3.3.2 Rendering Configuration

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.

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 (Space Property) 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.

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:

Doctype Home: Controls the location of the homepage of a given document type. Use the identifier of the doctype.
Subject 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	Enterprise Architect Image Link Macro	Production	Renders an image generated from an Enterprise Architect diagram, transcluded from a server.
2	HTML Snippet Macro	Production	Transclude HTML content from a remote server.
3	Hudson Link Macro	Deprecated	Render links to jobs and services on a Hudson server.
4	Javadoc Link Macro	Production	Links API documentation pages for Java elements.
5	Nexus Link Macro	Production	Renders a link to an artifact stored on a Nexus server.
6	Site Link Macro	Deprecated	Links to a resource on a versioned site.
7	Sonar Link Macro	Deprecated	Renders a link to a project on a Sonar service.
8	Subversion Link Macro	Deprecated	Renders a link to a resource on a Subversion (SVN) repository.
9	Subversion Transclusion Macro	Deprecated	Transcludes a snippet from a project on a Subversion (SVN) server.
10	System Image Link Macro	Production	Renders an image transcluded from a remote server.
11	System Link Macro	Production	Links to a resource on a server.
12	System Transclusion Macro	Production	Transclude content from a resource from a remote system.
13	Text Snippet Macro	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 Spaces	projectdoc introduces structure on a Confluence space. It adds the concept of homepages for document types.	topic
projectdoc Space Relationships	projectdoc allows to group spaces and to set them in two kinds of relationships: delegate and search.	topic
Accessing projectdoc Space Properties with cURL	Learn how to access projectdoc space properties via REST API with cURL.	topic
Display All Space Properties	Renders all properties referenced by the current space.	macro
Display Space Attribute Macro	Renders a space attribute value.	macro
Display Space Property Macro	Renders a space property value.	macro
Space List Macro	Renders spaces with their attributes in a table or list.	macro
Space Properties	Lists the configuration options at space level.	topic
Space Properties Extension	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
Space Property Controls	Lists valid controls for properties to be used as space properties.	topic
Spaces Introduction	Provides a gentle introduction to the concept of spaces using projectdoc.	topic

Get Started

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

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

Using Space Properties