Last updated Mar 27, 2024

Adding space shortcut links

Applicable:

This tutorial applies to Confluence 5.0.

Level of experience:

This is an intermediate tutorial. You should have completed at least one beginner tutorial before working through this tutorial. See the list of developer tutorials.

There are two kind of links in the space sidebar:

  • Main links
  • Space shortcut links (quick links)

This tutorial will explain how to create either of them. There is one additional kind of link:

  • Advanced screens. This part will not be treated in this tutorial, as it is not new to Confluence 5.0 - They are described on Web UI Modules as the location "system.space.admin".

Here is a comparison of the sidebar link types:

TypeWhen are they created?When are they removed?
Main Links
  • For all spaces, by default.
  • When the Space Administrator hides them.
  • When the plugin is uninstalled.
Quick Link / Space Shortcut Link
  • When the Space Administrator creates one,
  • When the user uses the Create button,
  • When a plugin calls the API.
  • When the Space Administrator removes them.

Download the example

The example below is available on the following BitBucket repository: https://bitbucket.org/atlassian_tutorial/space-plugin-example

Preparation

You need to create a Confluence plugin and update the version of Confluence to 5.0-m9.

Space shortcut link

If you have followed the Create content plugin, your users can now open the Create dialog to insert a new page. Content of the same type is grouped in a collector. A link to the collector is created automatically in the space sidebar. This is called a "Space Shortcut Link" or "Quick Link".

Quick Links are the preferred way to link to collectors. Below is the example of the "Meeting Notes" collector. As you can see, there is a Quick Link for "Meeting Notes" in the side bar, next to "Requirements".

Plugins using the confluence-create-content-plugin do not need to call the API, as the Quick Link is created when the user goes through the Create wizard.

There are other situations when you would like to create Quick Links. If your plugin relies on the confluence-create-content-plugin, the shortcut link is created automatically; Otherwise you will need to call the API.

Declare a dependency the confluence-space-ia plugin

In your pom.xml's <dependencies> section, add the following element:

1
2
<dependency>
    <groupId>com.atlassian.confluence.plugins</groupId>
    <artifactId>confluence-space-ia</artifactId>
    <version>${confluence.version}</version>
    <scope>provided</scope>
</dependency>

Import the component

In your atlassian-plugin.xml, import SidebarLinkService:

1
2
<component-import key="sidebar-link-service" interface="com.atlassian.confluence.plugins.ia.service.SidebarLinkService" />
1
2
// Get the ID of a page in the space
String id = Long.toString(space.getHomePage().getId());
// Note: Soon the API will use Long instead of String for the pageId.
if (sidebarLinkService.hasQuickLink(this.getSpaceKey(), id)) {
    sidebarLinkService.create(getSpaceKey(), id, null, null);
}

Parameters

For the method SidebarLinkService#create():

Name*Description
spaceKey

The key of the space where you want to insert your Quick Link.

Case-sensitive.

pageId

The ID of the content you want to link to. It can either be a Page or a Blog post.

The EAP API takes a String, but it will be changed to a Long in Confluence 5.0.

If null, the url is mandatory.

customTitle

The title of the link.

Default: Title of the target page or url.

urlIn case of a link to external content, url of the link.
iconClass

The CSS class of the icon.

Default: The default icon for Quick Links.

*spaceKey parameter is required

Main link

This section is presented as a second part of this tutorial because it is not the preferable way to link to collectors: See the table in the introduction.

Pages and Blogs are examples of Main Links:

Main Links are declared as Web-Items in atlassian-plugin.xml, under the location "system.space.sidebar/main-links". Here is the example for a custom link link:

1
2
<web-item key="plugin-content-main-link" name="Plugin Content" section="system.space.sidebar/main-links" weight="30">
    <label key="plugin.content.title"/>
    <link id="plugin-content-main-link-id">/plugins/${project.artifactId}/view-custom-content.action?key=$generalUtil.urlEncode($helper.spaceKey)</link>
    <styleClass>plugin-content-main-link</styleClass>
</web-item>

This Web Item conforms the the standard definition. The style class can be defined by a CSS as follows:

1
2
<!-- CSS for the plugin-content-main-link icon -->
<web-resource key="space-links-web-resources">
    <resource type="download" name="space-links.css" location="css/space-links.css"/>
    <context>main</context>
</web-resource>

It sometimes happens that you don't know the URL of the link at the time of writing atlassian-plugin.xml. You can inject it using a Context Provider. Please refer to:

Next Step

If you declare a main link for your custom content, you may want to create an index page for a custom content. See Writing an space index page for a content type.

Rate this page: