Extending the Confluence Insert Link Dialog
This tutorial applies to Confluence 4.0, and later
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 half an hour to complete this tutorial.
Overview of the tutorial
This tutorial shows you how you can add a panel to the Insert Link dialog in Confluence. The plugin you will create inserts a new tab called Demo in the dialog. When you click the Demo tab, the Demo panel appears with a single text box:
Our plugin simply converts text entered in the field into an HTML link. This is a simple plugin, but provides a starting point for the more advanced link dialog customizations you might like to add to Confluence.
To create this plugin, you will create a Confluence plugin consisting of the following components:
- A Google Closure "Soy" template for rendering the panel's HTML markup.
- A CSS file to provide styling for the panel.
- An internationalisation (i18n) properties file, to provide default English text for the panel
- A plugin descriptor file that describes the plugin and registers its modules with Confluence.
When you have finished, all these components will be packaged in a single JAR file.
To get the most out of this tutorial, you should be familiar with:
- The basics of Java development, such as classes, interfaces, methods, and so on.
- How to create an Atlassian plugin project using the Atlassian Plugin SDK.
- How to use and administer Confluence.
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 Git repository containing the tutorial's code. To clone the repository, issue the following command:
Alternatively, you can download the source as a ZIP archive by choosing download here: https://bitbucket.org/atlassian_tutorial/confluence-insert-link-demo-plugin.
Step 1. Create the plugin project
In this step, you'll use an
atlas command 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. They automate much of the work of plugin development for you.
- If you have not already set up the Atlassian Plugin SDK, do that now: Set up the Atlassian Plugin SDK and Build a Project.
- Open a terminal and navigate to the directory where you want to place your project files.
Enter the following command:
As prompted, enter the following information to identify your plugin:
- Confirm your entries when prompted.
Step 2. Clean up some project files
- Change to the new project directory created by the SDK,
- Remove the entire test directory at
You can also remove the Java files from your project by removing the
src/main/java directory. However, removing those files is not necessary. Keeping them gives you a place to put Java code if you plan to expand this plugin in the future.
Step 3. Create a Soy template for the custom panel
The SDK generated some resource files for us. However, we'll keep the resource files associated with this plugin in a separate directory, just for clarity.
First, create the Soy template used to generate our Insert Link panel:
- Change to the following directory under the new project home:
- Create a new directory called
This is where we'll keep the resource files specific for our plugin.
In the new directory, create a file named
Add the following content to the file:
The namespace must be
Confluence.Templates.LinkBrowser, as shown here. The name of the template,
-Panel. In this case, our panel's key is
demo, so the template name is
The template should contain the markup you want to appear in the body of the link dialog. In this case, we have a label with an i18n key of
link.browser.demo.link.label, a text box with the name
destination, and some description text with an i18n key of
- In the
src/main/resources/insert-linkdirectory, create a file named
Add the following content to the file:
- The panel key
demomust match the web-item link ID (see below) and the ID of the Soy template for the panel (see above).
$linkFieldvariable will be used to keep a jQuery reference to our link field, which will be used in several of the handler functions.
- The functions
handlesLinkare hooks called by the Insert Link dialog as the tab is respectively: initialised, displayed, hidden, submitted and opened in edit mode.
- The panel key
createPanelfunction in the scaffolding with our initialization logic:
This handler code does the following:
- Stores a reference to the panel element for future use.
- Finds the destination input field and stores a reference to a jQuery wrapper around that element for later use.
- Ignores the user hitting enter (keycode 13) in the form if the submit button is not enabled.
- Listens for "keyup" events on the link field, and updates the link destination as the user types. The link is created via
link-object.jsin the Confluence source code for information about other link types which can be inserted.
The only other handler we will implement for this tutorial is the
onSelectfunction, which will be as follows:
This handler code focuses the link text box when the panel is opened.
Step 5. Create CSS and i18n files to provide styling and text for the panel
- Create a file named
Insert the following CSS code into the file:
Add the following properties to the file:
The CSS and properties files will provide the styling and text for our panel.
Step 6. Register the plugin modules in the plugin descriptor
In the plugin XML descriptor file,
Open the plugin descriptor file and replace the existing content with the following:
The important parts of the plugin descriptor are as follows:
- The web-item create a new tab in the link dialog. This allows the new panel to appear. The
linkIdattribute on the link (in this case "demo") must match the key of the plugin and the name of the Soy template, as noted above.
- Both web-resources have a
editor, so they appear on any page containing the page editor. This means that your JS code will be included with the
batch.jsfile for pages that include "editor" in the URL.
- The i18n resource declaration references the path to the i18n file without a "properties" suffix.
Because your JS code is loaded the editor context, it will be included with the "batch.js" file that includes "editor" in the URL.
That's it! Now let's try the plugin.
Step 7. Try it out
Now start up Confluence and try out your plugin:
- 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:
- From your browser, open the Confluence URL indicated in the output.
- At the Confluence login screen, enter the username/password combination of
- Create a new page.
- In the edit pane for your page, click the link icon.
Confirm that the Demo tab appears in the Insert Link dialog. Also, make sure that the link insert pane appears with no errors.
If the Demo tab does not appear in the dialog, make sure you have the
web-item correctly registered in
atlassian-plugin.xml. Also make sure that you have installed the plugin in Confluence and it is enabled.