User's and Administrator's Guide (v 1.7.4)

Description/Features

The plugin provides functionality to organize spaces hierarchically in spaces and sub-spaces. It includes macros to display the space hierarchy on the dashboard or in navigation menus. The relationship between the spaces is rather lose (e.g. no permissions or layouts will be inherited), since the plugins focus is on structuring a wiki and its spaces.

Documentation

 

Configuration of space structures

There are two ways to configure the space structure - while administrators can change the structure for all spaces, space administrators are only allowed to create sub-spaces.

  • Administrators define the hierarchical structure of (existing) spaces via "Confluence Administration" > "Subspace Configuration". By changing the parent space of a space a hierarchical relationship is defined.
    • using the spacekey "dashboard" for the parent space will define a space as a top level space
  • Space administrators create sub-spaces the current space via "Space Admin" > "Create a sub-space"
    • There is a known issue with the create subspace view since Confluence 4.2.6 . Please see CSSP-87.
  •   

Macro {subspaces}

The macro {subspaces} allows to display the space structure with all spaces and subspaces. Several parameters allow to configure the way the structure is displayed. The macro browser is supported.

Parameters

ParameterDefaultDescription
style 
(style=menue) 
(style=list) 
(style=plain) 

menueOptional parameter, to define how the space structure is displayed: 
  • menue: horizontal navigation bar with some styling; showing the top level spaces, sub spaces are shown after a mouse-over
  • list: all spaces shown in a list (similar to the space overview that is displayed on the dashboard)
  • plain: pure HTML-list
sort 
(sort=creation) 
(sort=modification) 
(sort=title) 
(sort=mixed) 
creationOptional attribute that allows you to configure how the spaces are sorted. 
  • creation: sort by content creation date
  • title: sort alphabetically by title
  • modification: sort by last modification date
  • mixed: sort spaces in the first/top level by modification date and all sub spaces by title
keynoneOptional parameter to restrict the displayed space structure to a space and its sub-spaces (a subtree in the space hierarchy)
showRoot 
(showRoot=true) 
(showRoot=false)
falseIf the "key" parameter is defined, this parameter defines if the root node of the specified subtree is displayed. By default only the sub-spaces of the given spaces are displayed, but not the given space itself.
addlink 
(addlink=true) 
(addlink=false) 
falseSpecifies whether static links should be shown or not. Those links can be configured via "Confluence Administration"  > "Subspace Configuration"
displayEmptyMessage 
(displayEmptyMessage=true) 
(displayEmptyMessage=false) 
trueSpecifies whether to display a short message that the space structure that should be rendered is empty. Especially useful in combination with the parameter "key". 
  
maxDepth 
(maxDepth=2)
noneSpecifies the depth of the space hierarchy. maxDepth=0 shows no sub-spaces, maxDepth=1 shows the direct sub-spaces of a space.  If no parameter is given all sub-spaces will be shown. 
showSpaceIcons 
(showSpaceIcons=true) 
(showSpaceIcons=false) 
falseOptional parameter to show the space logos at the top level spaces. This parameter works only with the "menue" style.
showHomeButton 
(showHomeButton=true) 
(showHomeButton=false) 
falseOptional parameter to display a link to the dashboard. This parameter works only with the "menue" style.

Example: Navigation bar on every page

The common way

The following steps describe how to display a navigation bar on every page in the Default Theme. Custom themes have to be modified accordingly.

  • Edit the "Main Layout" (Via "Confluence Admin -> Layouts -> "Edit" the Main Layout)
  • Enter the following text just before the <div id="main">-Tag

     

    $helper.renderConfluenceMacro("{subspaces:addlink=true|currentSpace=$spaceKey}")
  • For a proper display of the navigation bar in the Default Theme, the Theme Integration module has to be activated.
    • the Theme integration module is part of the subspaces plugin and deactivated by default
    • Activation of plugin modules is possible via the Plugin Manager
    • For Custom Themes some CSS styling may be necessary.

The CUTE way

Example: Hierarchical space structure

The macro allows you to display a space hierarchy, similar to the space overview on the dashboard.

For Confluence 4.x

Go to your "Confluence Admin" -> "Plugins" -> "Manage Existing" -> "Subspace Plugin" and activate the Module "Subspaces Dashboard Panel (CF 4)". Now you have the Subspace Panel on your Dashboard.
If you want to remove the Confluence original space view at the Dashboard you have to deactivate the module "global-entities-panel" which is part of the "Dashboard Macros Plugin" (it is a system plugin).

For Confluence < 4

To display the overview on the dashboard edit the "Global Layout" (Via Confluence Admin -> Layouts -> "Edit" the Global Layout)

replace following code

 

$helper.renderConfluenceMacro("{spaces}")

 

with

 

 

$helper.renderConfluenceMacro("{subspaces:style=list|sort=title}")

 

Example: Space structure in the breadcrumbs

The plugin allows to display the hierarchical space structure in the Confluence breadcrumbs. To change the breadcrumbs on every page edit the "Main Layout" (Via "Confluence Admin -> Layouts -> "Edit" the Main Layout):

Macro {subspaces-quicksearch}

The "subspaces-quicksearch" macro provides a quicksearch field similar to the Confluence default quicksearch field. It provides a quick result dropdown and forwards to an advanced search result page too - but search results are limited to the current space and its subspaces. 

Parameters

ParameterDefaultDescription
includeSubspaces
(includeSubspaces=true)
(includeSubspaces=false)
trueThis Parameter defines whether the quicksearch dropdown should include the subspaces in its search or not.
spaceKey noneDefines the start spacekey to search into.

Advanced search results page

The subspaces advanced search site works like the original confluence search result page. But there is an additional checkbox "include subspaces" at the filter column. If you want to search in a specific space you have the choice to include its subspaces in the search by selecting the checkbox. Furthermore, all spaces at the first hierarchy level will be listed above the spaces selection box. Choosing one of these spaces initiates a search in this space and its subspaces.

Example: Replace the Confluence Quicksearch with the subspace Quicksearch

Edit the "main Layout" (Via Confluence Admin -> Layouts -> "Edit" the Main Layout).

Look for the line:

 

#quickSearch()

 

Replace it with:

Hints

Screenshots