Skip to end of metadata
Go to start of metadata
Level of experienceBEGINNER
Time estimate1:00
Atlassian applicationCONFLUENCE 4.X+

On this page:

Tutorial overview

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 

https://developer.atlassian.com/display/CONFDEV/Plugin+Tutorial+-+Extending+Autoconvert

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 JavaScript file to provide an Autoconvert handler.
  • Using a parseURI JavaScript object to interpret URLs.

Prerequisite knowledge

To complete this tutorial, you should already understand the basics of JavaScript development. 

Plugin source

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/.

About these Instructions

Icon

You can use any supported combination of OS and IDE to create this plugin. These instructions were written using Eclipse Indigo on Mac OS X. If you are using another OS or IDE combination, you should use the equivalent operations for your specific environment.

This tutorial was last tested with Confluence 5.2.3

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.

  1. Open a terminal and navigate to your Eclipse workspace directory.

  2. Enter the following command to create a Confluence plugin skeleton:

    $ atlas-create-confluence-plugin
  3. When prompted, enter the following information to identify your plugin:

    group-id

    com.atlassian.tutorial.confluence

    artifact-id

    confluence-autoconvert-dev-docs

    version

    1.0-SNAPSHOT

    package

    com.atlassian.tutorial.confluence

  4. Confirm your entries when prompted with Y or y.

    Your terminal notifies you of a successful build:

    [INFO] ------------------------------------------------------------------------
    [INFO] BUILD SUCCESSFUL
    [INFO] ------------------------------------------------------------------------
    [INFO] Total time: 1 minute 11 seconds
    [INFO] Finished at: Thu Jul 18 11:30:23 PDT 2013
    [INFO] Final Memory: 82M/217M
    [INFO] ------------------------------------------------------------------------
  5. Change to the project directory created by the previous step.

    $ cd confluence-autoconvert-dev-docs/
  6. 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:

    $ rm -rf ./src/test/java
    $ rm -rf ./src/test/resources/
  7. Delete the unneeded Java class files.

    $ rm ./src/main/java/com/atlassian/tutorial/confluence/*.java
  8. Edit the src/main/resources/atlassian-plugin.xml file.

  9. Remove the generated myPluginComponent component declaration.

  10. Save and close atlassian-plugin.xml.

Import your project into your IDE

 Click here to see instructions for importing into Eclipse

 

  1.  Make your project available to Eclipse.

    atlas-mvn eclipse:eclipse
    

    You'll see a successful build message: 

    [INFO] ------------------------------------------------------------------------
    [INFO] BUILD SUCCESSFUL
    [INFO] ------------------------------------------------------------------------
    [INFO] Total time: 54 seconds
    [INFO] Finished at: Tue Jul 16 11:03:59 PDT 2013
    [INFO] Final Memory: 82M/224M
    [INFO] ------------------------------------------------------------------------
  2. Start Eclipse.
    You can open a new terminal window to perform this action.

    $ cd ~/eclipse
    $ ./eclipse
  3. Click File > Import
    Eclipse starts the Import wizard.

  4. Expand the General folder tree to choose Existing Projects into Workspace.

  5. Click Next. 

  6. Click Browse and enter the root directory of your workspace.
    Your Atlassian plugin folder should now appear under Projects.

  7. Ensure your plugin checkbox is ticked and click Finish
    Eclipse imports your project, and it's now visible in your Package Explorer view. 

Step 2. Write the JavaScript for the autoconvert handler

Your plugin uses JavaScript to parse the URLs and return the title text. When you created your plugin project skeleton, it automatically included a directory for 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: 

https://developer.atlassian.com/display/CONFDEV/Adding+a+Custom+Action+to+Confluence

If split at the forward slashes, the link contains developer.atlassian.comdisplayCONFDEV, and the actual page title. You'll write JavaScript to use the fourth section as display text.

  1. Open confluence-autoconvert-dev-docs.js from src/main/resources/js.

  2. Add a bind method to listen for the init.rte event.

    The init.rte event is when the editor in Confluence is loaded.

  3. Create a handler that can later call the continuation done().

    Add and assign the variable pasteHandler within the curly brackets of the bind method. Include the arguments uri to reference a parseURI object, the jQuery object node, and done to act as a continuation function for pasteHandler to call. The parseURI object interprets URLs to get the title of the page. You'll add additional code inside the closing curly brace }.

  4. Add and assign directoryParts
    Since the URL is separated by forward slashes, you'll include this in the assignment statement:

  5. 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 uri.source.

  6. Define pageName as the fourth parameter ( [3]), and replace URL formatting with a space. 

    The done(node) method makes node available for additional URLs. 

    Call done() once in all code paths

    Icon

    In order for autoconvert to work, call done() exactly one time in all possible code paths. You can call done() with no arguments if you don't want to change the link, or you can pass the replacement or modified node to change the link.

  7. Finish your alternation by directing ineligible URLs to the done method.

    Call done() again to finalize the code path. This completes the block, and uses the closing }; that you added in step 1.

  8. Register the handler.

  9. Save the changes and close the file.
 Click here to expand...

Here's what your confluence-autoconvert-dev-docs.js file should look like at completion:


Step 3. Add a Web Resource module to the atlassian-plugin.xml descriptor 

Now you'll add a Web Resource module to the atlassian-plugin.xml file to describe how Confluence should interact with your JavaScript file. 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.

  1. Open atlassian-plugin.xml from src/main/resources.

  2. Locate the comment line <!-- add our web resources-->.
    Resources were automatically generated when you created the plugin skeleton.

  3. Add the following code to define the location of your JavaScript file.

    Here you'll add the JS file you just created.

  4. Save and close the file.

  5. Update your project changes from the project root.
    In this example, the command is for Eclipse:

    $ atlas-mvn eclipse:eclipse
 View the complete descriptor file.

Your 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.

  1. Open a terminal window and navigate to the plugin root folder. 

    $ cd confluence-autoconvert-dev-docs
  2. Start up Confluence from your project root using the atlas-run command.

    atlas-run
    

    This command builds your plugin code, starts a Confluence instance, and installs your plugin. This may take a few minutes.

  3. Locate the URL for Confluence.
    Your terminal outputs the location of your local Confluence instance, defaulted to http://localhost:1990/confluence.

    [INFO] confluence started successfully in 71s at http://localhost:1990/confluence
    [INFO] Type CTRL-D to shutdown gracefully
    [INFO] Type CTRL-C to exit
    
  4. Open your browser and navigate to your local Confluence instance.

  5. Login with admin / admin.

  6. Click Create to create a new Confluence page.

  7. Choose Blank page and click Create.

  8. 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:

    https://developer.atlassian.com/display/CONFDEV/Extending+Autoconvert
     
    https://developer.atlassian.com/display/CONFDEV/Extending+the+Confluence+Insert+Link+Dialog
     
    https://developer.atlassian.com/display/CONFDEV/Adding+a+Custom+Action+to+Confluence
    
  9. 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:
    Verify the URLs autoconvert

5 Comments

  1. Anonymous

    I've attempted running this and it does not seem to do anything. The environment is in 5.2.3 even when I do atlas-run --version 5.1.4 since that appears to be the last version this was tested on. I really can't tell if this is an issue because of the Confluence version or if this tutorial is incorrect somewhere in the source code.

     

    I do question why this bit is in the tutorial since it is not in the final code block.

    There is also an extra ')' in step 2 number 4

     

    1. Anonymous

      Okay, I got my dev environment to run on 5.1.4, but  auto-convert is still not working.

       

  2. Hi there,

    Thanks for letting us know! I've corrected the erroneous parenthesis and removed the unnecessary step. I haven't been able to replicate the problem you're running into, but I'd like to try to help. The plugin should install and run successfully even using Confluence 5.2.3.

    Clarify the following and I'll dig in further:

    • What error are you seeing? What's the result when you complete the tutorial?
    • What operating system are you using? 
    • What version of AMPS are you using? 

    For reference, here's what I had in my pom.xml

     

     

     

  3. Anonymous

    Hi,

     

    I'm on Ubuntu 13.04

    Amps version is 4.2.5

    I just realized that copying the links from this page and pasting into the confluence page makes them pre-formatted, but even when I change them to normal text, they just convert to a link instead of the text at the end of the link. I'm not getting any errors printing out.

     

    Thanks

  4. Anonymous

    Never mind, it is working now. I didn't realize it only worked when you paste a link in, not type it in and since the pre-formatting thing was messing it up before and doesn't register it as being pasted when you convert the text to something other than pre-format, I was not getting anything to work.