|Level of experience||BEGINNER|
|Atlassian application||CONFLUENCE 4.X+|
This tutorial shows you how to create a plugin that extends Confluence Autoconvert. Your plugin converts URL text into hyperlinked title text. The conversion appears dynamically as you edit in Confluence and add URLs from the http://developer.atlassian.com domain. In other words, your plugin converts URL text like the following from
into a link that displays as Plugin Tutorial - Extending Autoconvert. This particular plugin converts links from the developer.atlassian.com domain as an example, but could be modified for any domain.
Concepts covered in this tutorial:
- Using a
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 using the get source option here: https://bitbucket.org/atlassian_tutorial/extending-autoconvert-in-confluence/.
Step 1. Create and prune the plugin skeleton
In this step, you'll create a plugin skeleton using
atlas- commands. Since you won't need some of the files created in the skeleton, you'll also delete them in this step.
- Open a terminal and navigate to your Eclipse workspace directory.
Enter the following command to create a Confluence plugin skeleton:
When prompted, enter the following information to identify your plugin:
Confirm your entries when prompted with
Your terminal notifies you of a successful build:
Change to the project directory created by the previous step.
Delete the test directories.
Setting up testing for your plugin isn't part of this tutorial. Use the following commands to delete the generated test skeleton:
Delete the unneeded Java class files.
- Edit the
Remove the generated
Save and close
Import your project into your IDE
Make your project available to Eclipse.
You'll see a successful build message:
You can open a new terminal window to perform this action.
- Click File > Import.
Eclipse starts the Import wizard.
- Expand the General folder tree to choose Existing Projects into Workspace.
- Click Next.
- Click Browse and enter the root directory of your workspace.
Your Atlassian plugin folder should now appear under Projects.
- Ensure your plugin checkbox is ticked and click Finish.
Eclipse imports your project, and it's now visible in your Package Explorer view.
js and and empty file titled
confluence-autoconvert-dev-docs.js. In this step, you'll add a
bind method so your plugin executes during the
init.rte event – when you edit a page in Confluence. You'll also add an alternation so your plugin executes only on http://developer.atlassian.com links.
If URLs meet the criteria of the
if conditions, you'll use
uri, an object from
parseURI. This enables your plugin to parse a URL, splitting each section after the initial
// at single (
/) forward slashes. You can try it out here: http://stevenlevithan.com/demo/parseuri/js/
Your plugin converts http://developer.atlassian.com URLs to display as page titles, so it needs to be able to parse 4 parts of the URL:
If split at the forward slashes, the link contains
bindmethod to listen for the
init.rteevent is when the editor in Confluence is loaded.
Create a handler that can later call the continuation
Add and assign the variable
pasteHandlerwithin the curly brackets of the
bindmethod. Include the arguments
urito reference a
parseURIobject, the jQuery object
doneto act as a continuation function for
pasteHandlerto call. The
parseURIobject interprets URLs to get the title of the page. You'll add additional code inside the closing curly brace }.
Add and assign
Since the URL is separated by forward slashes, you'll include this in the assignment statement:
Nest a condition to only apply the autoconvert plugin to http://developer.atlassian.com pages.
Your condition verifies that the URL qualifies for the autoconvert action by checking for four parts in the URL and that the text matches the
pageNameas the fourth parameter (
), and replace URL formatting with a space.
nodeavailable for additional URLs.
Finish your alternation by directing ineligible URLs to the
done()again to finalize the code path. This completes the block, and uses the closing }; that you added in step 1.
Register the handler.
- Save the changes and close the file.
Here's what your
confluence-autoconvert-dev-docs.js file should look like at completion:
Step 3. Add a
Web Resource module to the
Now you'll add a
Web Resource module to the
atlassian-plugin.xml file was also generated when you created your plugin skeleton.
This module type defines the locations of other resources for your plugin to use, so you can use the
confluence-autoconvert-dev-docs.js that you wrote earlier to handle the conversion of URLs. While it's possible to add this module via the
atlas-create-confluence-plugin-module command, it's easier in this case to add it directly to your descriptor file.
- Locate the comment line
<!-- add our web resources-->.
Resources were automatically generated when you created the plugin skeleton.
Here you'll add the JS file you just created.
- Save and close the file.
Update your project changes from the project root.
In this example, the command is for Eclipse:
atlassian-plugin.xml should resemble the following:
Step 4. Build, install, and run your plugin
In this step you'll install your plugin and run Confluence. Then, to test your autoconvert plugin, you'll add links to a Confluence page from developer.atlassian.com.
Open a terminal window and navigate to the plugin root folder.
Start up Confluence from your project root using the
This command builds your plugin code, starts a Confluence instance, and installs your plugin. This may take a few minutes.
Locate the URL for Confluence.
Your terminal outputs the location of your local Confluence instance, defaulted to http://localhost:1990/confluence.
- Open your browser and navigate to your local Confluence instance.
- Login with
- Click Create to create a new Confluence page.
- Choose Blank page and click Create.
Copy and paste various links into your page, and confirm that they convert to their page titles.
Here's a handful you can use. You'll want to paste them into your URL address bar, and then copy the link:
- Verify the links transform into titles as you cut and paste them into the page.
Here's an example of the links as they should appear: