Skip to end of metadata
Go to start of metadata

Some very rough notes I took while learning to create an Atlassian Confluence plugin. Perhaps, I'll clean these notes up a bit when I create my next plugin.



Contents

Install the Atlassian SDK

See: Set up the Atlassian Plugin SDK and Build a Project

Create the Plugin Skeleton

Navigate to the directory on your system where you'd like to create your plugin.  The command we are about to run will create a folder with the plugin directories inside. 

Create directory /Users/cburleson/repos/test-conf-plugin

cd into the directory

atlas-create-confluence-plugin

The first time, Maven will download a bunch of packages.

Now you need to define some things:

Define value for groupId: : com.codyburleson.test
Define value for artifactId: : myPlugin
Define value for version: 1.0.0-SNAPSHOT: : 1.0.0-SNAPSHOT
Define value for package: com.codyburleson.test: : com.codyburleson.test.MyPlugin

You will then be prompted to confirm:

Confirm properties configuration:
groupId: com.codyburleson.test
artifactId: myPlugin
version: 1.0.0-SNAPSHOT
package: com.codyburleson.test.MyPlugin
 Y: : Y

Maven will download some more stuff.

Open eclipse and switch to the /repos workspace

The basic skeleton for your Atlassian JIRA plugin is created in a new myPlugin directory: 

Feel free to take a moment to explore the different files created by the Atlassian SDK before you continue. 

Change to the myPlugin directory and enter the following command: 

atlas-run

DO NOT FORGET TO USE CTRL-D TO SHUT THE atlas-run execution down gracefully!

This will download a bunch of stuff (Maven) and then run the product with your plugin installed.

Navigate to:

http://localhost:1990/confluence

Login with admin | admin

Go find your plugin in the manage page:

http://localhost:1990/confluence/plugins/servlet/upm/manage/all

Import Into Eclipse IDE

Import > Eisting Maven Projects and find the project with the pom.xml file.

Preferences > Maven

Add a new Installation and point to: /Applications/Atlassian/atlassian-plugin-sdk-6.2.14/apache-maven-3.2.1

Set Maven user settings so that the Global settings point to: /Applications/Atlassian/atlassian-plugin-sdk-6.2.14/apache-maven-3.2.1/conf/settings.xml


Panel Macro


cd /Users/cburleson/repos/confluence-panel-macro/panelMacro
atlas-run


Open the atlassian-plugin.xml file in your favourite editor.


Locate the end of the <web-resource>...</web-resource> section in the file and enter the following:



<xhtml-macro name="panel" class="com.codyburleson.confluence.macro.Panel" key='panel-macro'>
	    <description key="panel.macro.desc"/>
	    <category name="formatting"/>
	    <parameters/>
</xhtml-macro>

Open the file /src/main/resources/myConfluenceMacro.properties and add the following line at the bottom of the file:

panel.macro.desc="Cody Burleson's Panel Macro"

Create the 

com.codyburleson.confluence.macro package.

Create the Java file in that package...

Panel.java
package com.codyburleson.confluence.macro;

import com.atlassian.confluence.content.render.xhtml.ConversionContext;
import com.atlassian.confluence.macro.Macro;
import com.atlassian.confluence.macro.MacroExecutionException;

import java.util.Map;

public class Panel implements Macro {

    public String execute(Map<String, String> map, String s, ConversionContext conversionContext) throws MacroExecutionException {
        return "<h1>Hello World</h1>";
    }

    public BodyType getBodyType() { return BodyType.NONE; }

    public OutputType getOutputType() { return OutputType.BLOCK; }
}

This is the minimum skeleton your Macro will require to implement the confluence Macro class and display a Macro object in Confluence. 

In your terminal window, change directory back to the top directory for your plugin (eg cd /repos/confluence-panel-macro/panelMacro)

Run the command:

atlas-mvn package

You should see a confirmation message 

[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 4.656 s
[INFO] Finished at: 2016-10-10T18:33:09+10:00
[INFO] Final Memory: 37M/433M
[INFO] ------------------------------------------------------------------------

Monitor the window where confluence was run originally and confirm that QuickReload finished loading. You should see a confirmation message:

Here I got a stack trace error.

[INFO] [talledLocalContainer] java.lang.RuntimeException: Cannot getResourceAsStream(panelMacro_en_GB.properties): This operation must occur before the plugin 'com.codyburleson.confluence.panelMacro' is uninstalled
[INFO] [talledLocalContainer] 	at com.atlassian.event.internal.SingleParameterMethodListenerInvoker.invoke(SingleParameterMethodListenerInvoker.java:54)

I created the file: 

panelMacro_en_GB.properties

Important to REFRESH THE WORKSPACE after creating new files.

Then fun atlas-mvn-package again - and all was cool...


Now you can try adding the Macro to a test page in Confluence (you'll need to make a new Confluence Space and Page before you can test it out so go ahead and do that first).


Now, you will allow the user to specify their name using a parameter to learn about how parameters can be set, and used.

Open the atlassian-plugin.xml file in your favourite editor.

Locate the <parameters/> element within the <xhtml-macro> element you created in the first part of this tutorial.  


Replace the <parameters/> element with the following:


<parameters>
    <parameter name="Title" type="string" />
</parameters>

This specifies that the parameter is called 'Name' and is of type 'string'.  You can find the full list of types under the Parameters heading in the macro module documentation

Now modify the execute method in the Java class so it looks like this:

public String execute(Map<String, String> map, String s, ConversionContext conversionContext) throws MacroExecutionException {
    if (map.get("Title") != null) {

        StringBuilder sb = new StringBuilder();
        sb.append("<div class=\"panelHeader\">");
        sb.append(map.get("Title"));
        sb.append("</div>");
        return sb.toString();
        
    } else {
        return "<h1>Hello World!<h1>";
    }
}

REFRESH THE PROJECT and then execute atlas-mvn package.

Press CTRL-D to shut down the atlas-run session gracefully.


Reference Resources

Create a Confluence 'Hello World' Macro