HIVESTONE - Space Hierarchy & Breadcrumbs

Space Hierarchy & Breadcrumbs

Space hierarchy and Breadcrumbs plugin for Confuence can be used for following purpose:

- Creating Space hierarchy (Parent-Child relationship, grouping similar spaces)
- Breadcrumbs at top pages which provides easy navigation between spaces in hierarchy
- Creating child space of current space (only space admins can do this)
- Scoped search in any desired hierarchy or branch of hierarchy

Creating Space Hierarchy

Space hierarchy can be created by setting parent child relation between spaces. As soon as plugin is installed 'Hivestone' section is created under Space Admin section. Hivestone section provides 'Set Parent space' capability. After installing plugin Space Admin section will create Hivestone section as shown in image:

Creating sample space hierarchy - If we have a space named 'Continents' with spacekey 'continents' and there is another space named 'North America' with spacekey 'northamerica'. Similarly space having name 'USA' with spacekey 'usa' and space having name 'Canada' with spacekey 'canada'. If Space Admin->Hivestone->Set parent space of 'North America' is set to 'continents' and that of 'USA' and 'Canada' is set to 'northamerica' following hierarchy will be created (Continents and North America part)

Above hierarchy will be displayed at any place where 'Space Hierarchy' macro is used and spacekey 'continents' is provided as parameter to macro. Home page of space 'Continents' is good place to insert 'Space Hierarchy' macro for above case. Following similar steps we can create multilevel hierarchy structure. Example multilevel hierarchy could be like this:

Rest apis are also provided to update the Patent space setting and get the children space of provided space. Apis included in plugin are

- <Base URL>/rest/hcms_space_hier/1.0/space_settings/parent-fetch/space-key/{space-key} (GET)
- <Base URL>/rest/hcms_space_hier/1.0/space_settings/children-fetch/space-key/{space-key} (GET)
- <Base URL>/rest/hcms_space_hier/1.0/space_settings/parent-save (POST with data space-key and parent)

Breadcrumbs at top of pages

Breadcrumbs at top of pages could be displayed using 'hivestonebreadcrumb' macro which comes along with Space Hierarchy & Breadcrumbs plugin. To apply this macro globally General Configurations-> Look and Feel section could be used. {hivestonebreadcrumb} could be provide in header section.

In case some Theme is applied globally then Configure Theme link could be used to insert the macro in header of each page.

Breadcrumbs will appear at top of each page as shown in image

Scoped search can also be performed in any desired hierarchy or branch of hierarchy. By default plugin creates space category for every hierarchy as well as for every branch of hierarchy. Name of space category is similar to space name of root of hierarchy or root of a branch.

Confluence standard UI should be used to do scoped search. Standard UI has got FILTER BY section which has a field named Space category. On typing Space name of root of hierarchy or specific branch, UI presents checkbox option to select the desired category. Desired name should be checked to do scoped search.

Best part of plugin is that it does not impact the performance of Confluence server instance which maybe the case with other available plugins.

FAQ

Q. I want to see the each and every hierarchy of my Confluence site. How to do this?

Ans. It can be done using following steps-

- Set Parent Space of every root space of every hierarchy as 'dashboard'. In above explained example set parent space of 'Continents' and 'Hivestone' as 'dashboard'.
- Now use 'Space Hierarchy' macro and provide 'dashboard' as parameter to macro.
- Wherever you will use above macro with dashboard as parameter whole hierarchy will start appearing as macro output.

Q. I have got list of spaces with parent and child relationship. Can I insert this information in Space Hierarchy & Breadcrumbs plugin programatically without going through each space settings?

Ans. Yes, Space Hierarchy & Breadcrumbs macro provides open rest API to get and set parent child relationship. We have provided 3 api's to get and set relationship information.

<Base URL>/rest/hcms_space_hier/1.0/space_settings/parent-fetch/space-key/{space-key} (GET)
<Base URL>/rest/hcms_space_hier/1.0/space_settings/children-fetch/space-key/{space-key} (GET)
<Base URL>/rest/hcms_space_hier/1.0/space_settings/parent-save (POST with data space-key and parent)

Perl, python or java can be used to feed the information in system using above apis.

Sample Perl script to do above operations would look like this:

use RPC::XML;

use RPC::XML::Client;

use HTTP::Request::Common qw(POST);

use LWP::UserAgent;

use HTTP::Cookies;

use LWP::Simple;

use Data::Dumper;

$ua =LWP::UserAgent->new;

my $cookie = new HTTP::Cookies( ignore_discard => 1 );

$ua->cookie_jar( $cookie );

#Provide Confluence Wiki Base URL

our $server = "http://confluence.hivestone.com";

#$map_file should have list of parent and child spaces.

#Each line should contain one entry.

#Each line should contain either - Space_Name_of_Parent,Space_Name_of_Child

#or line should contain - Space_key_of_parent,Space_Key_of_Child

our $map_file = "Subspace_Parent_Child_Hierarchy.txt";

#If file has space names then $file_has_space_names should be 1

#If file has space keys then $file_has_space_names should be 0

our $file_has_space_names = 1;

print "#####################################################################\n";

print "This script updates the space hierarchy as per parent child \nrelationship provided in file '$map_file' \n\n";

print "Confluence Wiki Base URL as provided is '$server'\n\n";

print "#####################################################################\n\n";

print "Please provide Username for login to Wiki:";

our $username = <STDIN>;

chomp($username);

print "Please provide password for '$username':";

our $password = <STDIN>;

chomp($password);

our %space_Name_Key_Map;

our @parent_child_relationships ;

my $URLPrefix="$server/rest/hcms_space_hier/1.0/space_settings";

open(FILE,"$map_file") || print "Unable to read $map_file \n";

@parent_child_relationships = <FILE> ;

close(FILE);

my $relationship_count = $#parent_child_relationships + 1 ;

print "Total parent child relationships provided in '$map_file': $relationship_count \n";

my $rpcserver="$server\/rpc\/xmlrpc";

our $client = RPC::XML::Client->new($rpcserver);

$token = login_to_wiki();

if($file_has_space_names == 1){

&get_spaces_namekeymap();

}

&create_space_hierarchy();

sub login_to_wiki() {

# Connect to wiki

my $response = $client->send_request('confluence2.login', $username, $password);

if (undef == $response) {

my $msg = "Undefined response from wiki server while trying to login to Confluence.\n";

print $msg;

print LOGFILEH $msg;

$response = $client->send_request('confluence2.login', $username, $password); # Try again

if (undef == $response) {

die "Quitting..\n";

}

my $newToken = $response->value;

return $newToken;

}

sub get_spaces_namekeymap () {

print "Getting space information from Wiki\n";

$response=$client->send_request("confluence2.getSpaces",$token);

#print Dumper($response) ;

my @spaceSummaries=@{$response->value};

my $space_count = 0;

my $spaceKey = "";

my $spaceName = "";

foreach $spaceSummary(@spaceSummaries)

{

$spaceKey = $spaceSummary->{key} ;

$spaceName = $spaceSummary->{name};

$space_Name_Key_Map{$spaceName} = $spaceKey;

#print "KEY::$spaceKey, NAME::$spaceName \n";

$space_count += 1;

}

print "Total Wiki spaces Visible to you: $space_count\n\n";

}

sub create_space_hierarchy() {

foreach $relation (@parent_child_relationships) {

my @array = split(",", $relation);

my $parent = $array[0];

$parent = &trim($parent);

my $child = $array[1];

$child = &trim($child);

my $parent_key = "";

my $child_key = "";

if($file_has_space_names == 1){

if(exists $space_Name_Key_Map{$parent} ){

$parent_key = $space_Name_Key_Map{$parent} ;

}else{

print "No space found for provided parent Space Name '$parent' \n";

next;

}

if(exists $space_Name_Key_Map{$child} ){

$child_key = $space_Name_Key_Map{$child} ;

}else{

print "No space found for provided child Space name '$child' \n";

next;

}

}else{

$parent_key = $parent;

$child_key = $child;

}

my $status = &setParent($parent_key,$child_key);

if($status == 1){

print " Setting parent of '$child':$child_key as '$parent':$parent_key - SUCCESS\n";

}else{

print " Setting parent of '$child':$child_key as '$parent':$parent_key - FAIL\n";

}

#####Check the parent space

#&getParent($child_key);

#####Check the chldren spaces

#&getChildren($parent_key);

}

sub getParent($) {

my($spacekey) = @_ ;

#Get parent space of given space

my $Get_from_url = "$URLPrefix/parent-fetch/space-key/$spacekey";

my $request=HTTP::Request->new (GET => "$Get_from_url");

$request->authorization_basic("$username","$password");

my $response = $ua->request($request);

#print Dumper($response);

#print "Request status: ";

#print $response->is_success;

#print "\nResponse Message: $response->{_content}";

}

sub getChildren($) {

my($spacekey) = @_;

#Get child space of given space

$Get_from_url = "$URLPrefix/children-fetch/space-key/$spacekey";

my $request=HTTP::Request->new (GET => "$Get_from_url");

$request->authorization_basic("$username","$password");

$response = $ua->request($request);

#print Dumper($response);

print "Response Message: $response->{_content}";

}

sub setParent($$) {

my($parent_spacekey, $spacekey) = @_ ;

#Set parent space of given space

my $POSTFROMURL="$URLPrefix/parent-save";

my $post_data="space-key=$spacekey&parent=$parent_spacekey";

my $request=HTTP::Request->new (POST => "$POSTFROMURL");

$request->authorization_basic("$username","$password");

$request->header("X-Atlassian-Token" => "no-check"); #This may be required if there is some configuration issue

$request->content($post_data);

my $response = $ua->request($request);

#print Dumper($response);

#print "Response status: ";

#print $response->is_success ;

#print "\nResponse Code: $response->{_rc} \n";

return $response->is_success ;

}

sub trim() {

my ($name) = @_;

$name =~ s/^\s+//;

$name =~ s/\s+$//;

return $name;

}

Q. I used markup {spacehierarchy:SpaceKey=spacekey|order=Alphabetical} to see a space hierarchy in sidebar of a space but bulleting and indentation is not as expected. How to correct the hierarchy display in sidebar?

Ans. Confluence has different style for items display in sidebar. To modify the space hierarchy display as per side bar navigation tree following CSS can be added in global style of Confluence instance.

/* This block re-enables bullets and indentation for the list items generated by the Hivestone SpaceHierarchy macro, which allows it to be inserted in the custom Sidebar code for any space. */

ul.hivestone-subspacemenu {

padding-left : 10px;

list-style-type : disc;

}

ul.hivestone-subspacesubmenu {

padding-left : 10px;

list-style-type : disc;

}

/* This does the same for columnar pages. Only need to override the first level of the UL. It requires a larger number for the bullet to render fully, but didn't want to make the left sidebar 7px wider. */

.columnLayout ul.hivestone-subspacemenu {

padding-left : 17px;

}

Credits

Our customers play and important role in making our solution better. Thanks to everyone who provided feedback, suggestions and reported some issues. Special thanks to Scott Taylor of Nvidia to work on style sheet to correct display of hierarchy at side bar of Confluence Space.

Atlassian Marketplace Link of this plugin - Space Hierarchy & Breadcrumbs