Setting up hierarchical spaces
- Robert Alexander Marshall
Setting up hierarchical spaces states
Overview
Although Confluence provides access to the page hierarchy in a space, the default for the spaces is for a flat hierarchy. As your content grows, spaces increase - this becomes harder and harder to manage. Grouping spaces together may help in managing the content for users.
The Comala Metadata App provides the ability to define space hierarchies by utilizing space metadata. A single piece of space metadata can be attached to the home page of a space indicating the key of its parent space.
Comala Metadata macros
The Comala Metadata App provides a number of macros to support the process of setting up a space hierarchy:
Using these macros, there are three steps to setting 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 for a space hierarchy
The first thing to do is to decide upon a root space. Most non-hierarchical wiki installations would not currently have a root space, so in that case 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 will be shown as the root of the breadcrumb.
In addition, it would be good to set the root space to be the site home page for your site. You can set 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 there further descendants for any of these spaces in the hierarchy, 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 add the macro to a page:
This displays a space breadcrumb from the current page (Development) to the chosen option of the instance Dashboard.
However 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.
The simplest way is to 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 an titled info message panel):
The breadcrumb is displayed according to the location of of the space of the current page in the defined space hierarchy.
Note that if there are any spaces in the instance that are not in the set hierarchy, as the header is a global setting, this breadcrumb will still be present on the pages in that space. The breadcrumb will render according to the individual space with no reference to the set space hierarchy.
To avoid the display of the breadcrumbs in any non-hierarchical spaces, the space-breadcrumbs macro must be added to the global Layout file or stylesheet. For example, as part of custom HTML/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 Comala 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 users personal spaces in the instance
The home page of the current space is now the root of all user spaces. It is also has the instance root space as it's parent space
A useful option is to add the users-report macro directly onto this page (but be careful as this assumes that you don't have many users).
The users-report can be configured to add internal metadata for each user as well as Comala Metadata App created space metadata from each user space.
In the example, only user admin has a personal user space. Space metadata has been added to the admin user personal space to record their location.