Setting up hierarchical spaces
Overview
Although Confluence provides access to the page hierarchy in a space, the default is a flat hierarchy. As your content grows, spaces increase—this becomes harder and harder to manage. Grouping spaces together can help users manage the content.
The Comala Metadata app lets you to define space hierarchies by utilizing space metadata. A single piece of space metadata can be attached to a space's home page, indicating the key of its parent space.
Macros
The Comala Metadata App provides a number of macros to support the process of setting up a space hierarchy:
Steps
Using these macros, there are three steps to set up hierarchical spaces:
In addition to having a root space, the user-space macro can be used to define a parent space for the personal spaces in the instance.
Create a root space
The first thing to do is to decide upon a root space for a space hierarchy. Most non-hierarchical wiki installations do not currently have one, so you should create one.
For example, in our company instance for Stars Like Dust, the following spaces have been created:
Space | Parent |
|---|---|
Stars Like Dust | Root space |
People | Stars Like Dust |
Quality | Stars Like Dust |
Development | Stars Like Dust |
The root space should probably have the same name as the wiki itself, because it is shown as the root of the breadcrumb.
In addition, it would be good to set the root space to be the site’s home page. You can do this in the Confluence global Administration under Configuration/General Configuration.
Add parent metadata to every other space
For all the spaces you require in the hierarchy, add the {parent-space} macro to the home page of each space, adding the space key for the root space to the macro placeholder:
In this example, the space key for the selected root space Stars Like Dust is SLD, and the addition of the parent-space macro sets the current space as a child of this SLD space.
Once added to the page, the hierarchy metadata is available to other metadata macros.
Add the space-hierarchy macro to the Stars Like Dust home page:
With the space key empty, this will display the hierarchy set for the spaces relative to the current page.
If any of these spaces in the hierarchy have further descendants, you can add the metadata to the child pages with the space key for the appropriate parent.
For example, if you require project spaces for Development, these can be added into a secondary level of the hierarchy
Space | Parent |
|---|---|
Stars Like Dust | Root space |
Development | Stars Like Dust |
Project Ascension | Development |
Project Stellar | Development |
To create the hierarchy, the parent-space macro is added to each of the project space homepages, configured with the space key of the Development space:
The space-hierarchy macro to the Stars Like Dust home page will now display:
Add the space-breadcrumbs macro
The space-breadcrumbs macro analyses the space hierarchy information. It can be added to any page.
The simplest way is to add the macro to a page:
This displays a space breadcrumb from the current page (Development) to the chosen option of the instance Dashboard.
This is more useful if added automatically for each page. Unfortunately, the macro cannot update the site breadcrumb. However, this can be done by adding the macro using one of the Look and Feel options in Confluence global administration:
add the macro to the header in the Sidebar, Header and Footer option
This displays the space breadcrumb for all the pages in each of the spaces in the hierarchy (in this example, within a titled info message panel):
The breadcrumb is displayed according to the location of the space of the current page in the defined space hierarchy.
If there are any spaces in the instance that are not in the set hierarchy, as the header is a global setting, this breadcrumb is still present on the pages in that space. The breadcrumb renders according to the individual space with no reference to the set space hierarchy
To avoid the breadcrumbs being displayed in non-hierarchical spaces, the space-breadcrumbs macro must be added to the global Layout file or stylesheet. For example, it could be part of custom HTML or CSS for the layout, with a conditional display of the breadcrumb on the presence of the space in the set hierarchy.
Create a 'Users' space
In addition to having a root space, it seems to be useful to also have a Users space. This is conceptually the parent space of every personal space, and helps to provide another level of structure if required.
If you require a user space, you should put the following metadata macros into the home page for the designated Users space:
parent-space adds the space to the hierarchy
user-space sets the space as the home page for any personal spaces in the instance
Need support? Create a request with our support team.