Extending the Macro Property Panel
This tutorial applies to Confluence 4.3
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.
It should take you approximately 1 hour to complete this tutorial.
|Status:||LEGACY This tutorial applies to Confluence versions that have reached end of life.|
Overview of the tutorial
The macro property panel allows a user to remove or edit the currently selected macro. This tutorial will show you how to extend this to add custom buttons.
We are going to create a status light macro that will render in the editor with additional buttons in the property panel to change the current status - from 0 to 100 percent.
To complete this tutorial, you need to know the following:
- The basics of Java development: classes, interfaces, methods, how to use the compiler, and so on.
- How to create an Atlassian plugin project using the Atlassian Plugin SDK.
- How to write a Confluence plugin that provides a macro
We encourage you to work through this tutorial. If you want to skip ahead or check your work when you have finished, you can find the plugin source code on Atlassian Bitbucket. Bitbucket serves a public Mercurial repository containing the tutorial's code. To clone the repository, issue the following command:
Alternatively, you can download the source using the get source option here: https://bitbucket.org/atlassian_tutorial/confluence-status-light-macro/overview
Step 1. Create the plugin project
In this step, you'll use the two
atlas- commands to generate stub code for your plugin and set up the stub code as an Eclipse project. The
atlas- commands are part of the Atlassian Plugin SDK, and automate much of the work of plugin development for you.
- Open a terminal and navigate to your Eclipse workspace directory.
Enter the following command to create a plugin skeleton:
When prompted, enter the following information to identify your plugin:
- Confirm your entries when prompted.
- Change to the
status-lightdirectory created by the previous step.
Run the following command:
- Start Eclipse.
- Select File > Import.
Eclipse starts the Import wizard.
- Filter for Existing Projects into Workspace (or expand the General folder tree).
- Choose Next and enter the root directory of your workspace.
Your Atlassian plugin folder should appear under Projects.
- Select your plugin and choose Finish.
Eclipse imports your project.
Step 2. Review and tweak the generated stub code
It is a good idea to familiarise yourself with the stub plugin code. In this section, we'll check a version value and tweak a generated stub class. Open your plugin project in Eclipse and follow along in the next sections.
Add plugin metadata to the POM
The POM (Project Object Model definition file) is located at the root of your project and declares the project dependencies and other information.
Add some metadata about your plugin and your company or organisation.
- Edit the
pom.xmlfile in the root folder of your plugin.
Add your company or organisation name and your website to the
- Save the file.
Verify your Confluence version
When you generated the stub files, a default Confluence version was included in your
pom.xml file. Take a moment and examine the Confluence dependency:
- Open the
- Scroll to the bottom of the file.
- Find the
This section lists the version of the Confluence and also the version of the
atlas-commands you are running.
- Verify that the Confluence version is the one you want.
- Save the
Review the generated plugin descriptor
Your stub code contains a plugin descriptor file
atlassian-plugin.xml. This is an XML file that identifies the plugin to the host application (Confluence) and defines the required plugin functionality. In your IDE (integrated development environment, such as Eclipse or IDEA) open the descriptor file which is located in your project under
src/main/resources. You should see something like this:
Step 3. Add your plugin modules to the plugin descriptor
The plugin skeleton contains code for a Confluence macro with key 'my-macro'. We will remove this, and replace it with a new plugin module for the status light macro:
- Open the
- Find the existing
<xhtml-macro>element and remove all the content contained within.
- Replace with the following details:
description="Percentage based status lights"
- Add a field named parameters, where we will add 11 parameters, one representing each image we have in the project - this allows us to set a percentage as a parameter and have it render the correct image.
- We will also register as a resource the images for the macro.
- Next what we will do is copy in all of the images required for the project, for this I am using PNG images representing progress bars available from Wikimedia Commons. Place these in the
The finished code should look like this:
Step 4. Update your project and refresh your IDE
If you change your Atlassian project, Eclipse is not automatically aware of the changes. Moreover, sometimes your project dependencies require an update. We need to fix that.
- Switch to a terminal window.
- Change directory to the project root.
This is the directory that contains the
Update your project metadata with the new POM information.
- Back in Eclipse, refresh the plugin project to pick up the changes.
Remember to do this update and refresh step each time you edit your
pom.xml and whenever you modify your plugin source with an Atlassian command.
Step 5. Write the plugin code
You have already generated the stubs for your plugin modules. Now , you will write some code that will make your plugin do something. Recall that this plugin provides a status light macro that will render in the editor with additional buttons in the property panel to change the current status . To do this, you will implement three interfaces:
Macro for the Macro itself and
ResourceAware for rendering it in the editor.
First, remove the example class that was created in the plugin skeleton at
Also remove the test class at
We will now create a new macro class at
com.atlassian.plugins.tutorial.confluence.StatusLightMacro. The macro implements three interfaces,
Macro for the Macro itself and
ResourceAware for rendering itself in the editor.
Extending the property panel
So far everything has been fairly standard, we have a macro that can render itself in the editor and a bunch of images to support it.
What we are going to do now is extend the macro definition to include the definition of a some custom buttons in the property panel. Each button will be given an id and a label that will be rendered, we will do this for all 11 states of the macro. Below is the new
xhtml-macro block with the property panel buttons.
Notice that the
context is set to
Confluence now provides a mechanism for plugin developers to hook into the events of their custom buttons on the property panel, this method is:
id is the id you have registered your button as in the
atlassin-plugin.xml file and the handler is a function callback that will be run when your button is clicked, this function gets passed the event object and the currently selected macro node. Below is a snippet of the
status-light.js provided in the source:
Notice that this snippet only handles the button with the id of
0, for brevity I have excluded the rest of the handlers (they change only in id and percentage values). The function defined at the top,
updateMacro is used to modify the macro parameters and redraw the macro in the editor.
Step 6. Build, install and run the plugin
Follow these steps to build and install your plugin, so that you can test your code.
- Make sure you have saved all your code changes to this point.
- Open a terminal window and navigate to the plugin root folder (where the
Run the following command:
This command builds your plugin code, starts a Confluence instance, and installs your plugin in it. This may take several seconds. When the process has finished, you will see many status lines on your screen concluding with something like the following:
- Open your browser and navigate to the local Confluence instance started by
For example, the default address is http://localhost:1990/confluence for Confluence. See Plugin SDK Supported Applications and Default Ports for other applications.
- At the HOSTAPP login screen, enter a username of
adminand a password of
- Add a page, and insert the status-light macro we have created.
The macro will render itself as an image placeholder within the editor:
Selecting the macro will display our extended property panel: