Rate this page:
This tutorial applies to Confluence 4.3 and earlier.
Level of experience:
Beginner. Our tutorials are classified as 'beginner', 'intermediate' and 'advanced'. This one is at 'beginner' level, so you can follow it even if you have never developed a plugin before
It will take you approximately 1 hour to complete this tutorial.
|Status:||LEGACY This tutorial applies to Confluence versions that have reached end of life.|
This tutorial shows you how to use a Web UI module in your plugin, to insert a menu option in to the Confluence web interface. The Web UI module can also insert links, tabs and sections of links. Read more about web item plugin module.
In order to do this, you will create a very simple Confluence plugin. Your plugin will consist of the following components:
All these components will be contained within a single JAR file. Each component is further discussed in the examples below.
NOTE: A more sophisticated plugin would also contain Java classes encapsulating the plugin logic. In this case however, we are simply concentrating on only adding a Web UI Module to Confluence -- we'll put an existing Confluence action in place for the button to activate.
We encourage you to work through this tutorial. If you want to skip ahead or check your work when you are done, you can find the plugin source code on Atlassian Bitbucket. Bitbucket serves a public Git repository containing the tutorial's code. To clone the repository, issue the following command:
$ git clone https://email@example.com/atlassian_tutorial/confluence-web-item.git
Alternatively, you can download the source using the Downloads page here: https://bitbucket.org/atlassian_tutorial/confluence-web-item
Ensure that you have the latest version of the Atlassian Plugin SDK installed on your machine. For more information, see Set up the Atlassian Plugin SDK and build a project
In this step, use the appropriate command to create your plugin. For example, . The commands are part of the Atlassian Plugin SDK, and automate much of the work of plugin development for you.
Enter the following command to create a plugin skeleton:
When prompted, enter the following information to identify your plugin:
Confirm your entries when prompted.
In this step, you must now register the plugin module in your plugin descriptor, . In other words, add the following code to your file between the tags, but below the tag group.
1 2 3 4 5 6 7 8
<web-item key="spacelogo" name="Space Logo" section="system.content.add/space" weight="40"> <label key="webitemz.new.item" /> <link>/spaces/configurespacelogo.action?key=$space.key</link> <icon height="16" width="16"> <link>/images/icons/logo_add_16.gif</link> </icon> <condition class="com.atlassian.confluence.plugin.descriptor.web.conditions.NotPersonalSpaceCondition"/> </web-item>
Let's break down that XML code. In this example we are adding an item to the Tools menu in Confluence, which will open the Customise Space Logo page when it's clicked.
To do this, we've done a number of things.
In the code above, this line involves four attributes:
<web-item key="spacelogo" name="Space Logo" section="system.content.add/space" weight="40">
In the code above, this part:
1 2 3
<icon height="16" width="16"> <link>/images/icons/logo_add_16.gif</link> </icon>
Defines a small graphic icon that will appear in the menu. Height and width are for controlling presentation of the graphic, while link points to the location of the graphic file (in this case we are using a graphic that ships with Confluence).
Examining this line of code:
This causes the web item to only be displayed in spaces that are not personal spaces. It does this by using a 'web condition'. Web conditions control the display of web items; more information is available in the reference documentation for Confluence plugin development.
In the code above, this line: defines the label for the button text that will appear in the menu.
We will want to specify a text label to display in our Confluence menu item. You could hard-code this information into your file, but by adding it in a new resource file, we can make our plugin compatible with internationalisation. To do so, simply add a new file in the resources directory of your plugin (called ) and enter one line of code into it:
webitemz.new.item=Configure space logo
Additionally, we will need to reference this resource file in our file. To do this, add this line of code above the code block:
<resource type="i18n" name="i18n" location="message" />
This will access your file and retrieve the text for our button label. The result of this is that the text we have specified here; 'Configure space logo' appears as the title text of our new button in the Add menu.
If you would like to know more about internationalisation, see our Confluence documentation on the topic.
Follow these steps to build and install your plugin, so that you can test your code. If you have not already started the application, start it now:
Go back to the browser. The updated plugin has been installed into the application, and you can test your changes.
The atlas-run command will compile the plugin project and then launch a local instance of Confluence.
Once Confluence has loaded, access the local instance with this URL:
Login with username "admin" and password "admin, then create a page in the default space. Give it a meaningful name and click Save to create the page.
On accessing the 'Add' menu, you will be able to see the new web item that you've added inside the menu. Clicking it will launch the 'Customise Space Logo' screen.
Screenshot: The New Web Item in the Confluence Add Menu
That's all that's required to add a menu item in a Confluence plugin. To extend this project, you could build new functionality for your button to activate.
Now you are ready to move onto writing some Java code to achieve that. It's not necessary, for the purposes of this tutorial though.
If you wanted to move on to writing Java to make new functionality to go with your web item, you can create an action with the XWork-WebWork Module.
Rate this page: