Adding items to the Info Banner
This tutorial applies to Confluence 5.4.
Level of experience:
Intermediate. Our tutorials are classified as 'beginner', 'intermediate' and 'advanced'. This one is at 'intermediate' level, so you will need to have developed a few plugins before to follow it.
It will take you approximately 1 hour to complete this tutorial.
The source code of the plugin used in this tutorial is hosted on Bitbucket: confluence-banner-tutorial.
On this page:
The Info Banner was added in Confluence 5.4 and allows plugin developers to add items that display additional information about a page or blogpost. The JIRA Links button, also released with Confluence 5.4, is a good example of how the Info Banner can be used to display information about a page. See new integration with JIRA.
The plugin in this tutorial inserts a new item called "Some statistics" to the Info Banner. Clicking this item launches a dialog, which contains some basic information about the page (number of likes, comments and versions). From this starting point, it is possible to create more advanced plugins to show any type of customised information.
Screenshot: The demo 'Some statistics' item and dialog.
In order to do this, you will create a Confluence plugin, which will consist of the following components:
- A Google Closure "Soy" template for rendering the dialog's HTML markup.
- A CSS file to make everything look nice.
- An internationalisation (i18n) properties file, to provide default English text for the panel.
- A REST Module to provide the information for the dialog to render when the item is clicked.
- A plugin XML descriptor file which registers all the plugin modules with Confluence.
The extension point used by this plugin is only available in Confluence 5.4 and later.
Step 1. Create the Plugin Project
The Atlassian Plugin SDK provides a number of
-plugin commands that you can use to generate stub code for your plugin.
- Run the atlas-create-confluence-plugin command and enter the following information when prompted:
- Open the
pom.xmlfile that was generated by the previous step, and update the information in this file to match your organisation and project name.
- You can remove the generated Java classes in
src/main/javaas we will be creating some new ones.
- Make sure the correct Confluence version is specified in
pom.xml(at least 5.4).
Step 2. Add a web item to the banner
In the plugin XML descriptor file,
src/main/resources/atlassian-plugin.xml, we need to register a web-item for the banner in the section
It is important to note:
- We are using an optional icon.
- Atlassian CSS classes for the basic styling. See Atlassian Design Guidelines for more information.
Don't forget to add the corresponding images and i18n resource (
src/main/resources/banner-stats.properties) to supply the label text.
Make sure the context tag is "viewcontent" as that is the context where the banner gets loaded, so it is also the one where you want to make your resources available.
src/main/resources/js/banner-stats.js, with the following content:
Don't forget to add the corresponding resource definition and it's dependencies in
Now let's add some content in there.
Step 4. Create a REST resource to retrieve data
src/main/java/directory, create a Java class in the corresponding package with the data we want to show.
The annotations in this class allow the server to return the information contained in the instances of this class as either XML or JSON depending on the client request or other configuration.
Create also the REST Resource to respond to web requests for this information.
This class basically will, given a pageId, build and return the data we want to use as a JSON object.
Don't forget to define the REST resource in
Check the REST Module page for more detailed information about how REST resources work.
Step 5. Create Soy templates to render the data in the dialog
- In the
src/main/resources/directory, create a new directory for your plugin resources called
Create a new Soy template -
src/main/resources/soy/banner-stats.soy, with the following content:
The template should contain the markup you want to appear in the dialog. In this example we have templates for displaying a spinner while loading the information, the content the dialog, and an error.
Don't forget to add the soy file and it's dependencies to
src/main/resources/atlassian-plugin.xml, as well as the new messages to the properties file.
src/main/resources/js/banner-stats.js as follows.
What we do here is:
- If the data is not already loaded, set the content of the dialog with the spinner template.
- Call the REST resource to get the data using a URL according to its configuration and passing the necessary parameters.
- Show the dialog.
- Once the server returns a response, we render the error or the information template accordingly.
Step 7. Create CSS to provide styling for your components
src/main/resources/css/banner-stats.csscontaining the following CSS to apply styling to the spinner and the button. You could add styles that apply to the dialog too.
As always, don't forget to add your new resource to
Step 8. Install into Confluence
You can start an instance of Confluence with
atlas-run, or build the plugin with
atlas-package and install it into your existing Confluence instance.
The result when opening a page and clicking the banner item we created should look like the screenshot below.
Screenshot: The demo 'Some statistics' item and dialog
- If the new item does not appear on the banner, ensure you have the web-item correctly registered in
atlassian-plugin.xmlfor section "page.metadata.banner". Ensure you have installed the plugin in Confluence and that the plugin is enabled.
- If the dialog is not displaying information check that you are using the proper URL or check for errors in the application log or by debugging the server side code.
Other important considerations
Currently, the render of the banner items blocks the page render so if getting the information you need to render the item properly can take too much time, you should consider caching it if possible and retrieve it asynchronously when it's not cached (you could place a hidden web item and make it visible if appropriate when retrieving the information needed with an AJAX call after the page is loaded).