Create a Confluence 'Hello World' macro

This tutorial builds on the concepts introduced in Set Up the Atlassian SDK and Build a Project. You'll delve a little deeper into the SDK environment and so to complete this tutorial successfully, you should have already installed the SDK and created a plugin project.

About this tutorial

Create the plugin skeleton

Just like in the last tutorial, you'll use the Atlassian Plugin SDK to create a skeleton for our plugin.  This time you will use the atlas-create-confluence-plugin command because you're creating a plugin to work in Confluence.

1. Open a terminal window and navigate to the directory where you'd like to create your plugin.

2. Run the command atlas-create-confluence-plugin and fill in the plugin details as follows:

   1
   2
   Define value for groupId: : com.atlassian.tutorial
   Define value for artifactId: : myConfluenceMacro
   Define value for version:  1.0.0-SNAPSHOT: :
   Define value for package:  com.atlassian.tutorial: :
   Confirm properties configuration:
   groupId: com.atlassian.tutorial
   artifactId: myConfluenceMacro
   version: 1.0.0-SNAPSHOT
   package: com.atlassian.tutorial
    Y: : Y
   

3. The plugin skeleton will be created automatically and you'll receive a confirmation message as follows:

   1
   2
   [INFO] ------------------------------------------------------------------------
   [INFO] BUILD SUCCESS
   [INFO] ------------------------------------------------------------------------
   [INFO] Total time: 02:53 min
   [INFO] Finished at: 2016-10-10T15:39:56+10:00
   [INFO] Final Memory: 16M/309M
   [INFO] ------------------------------------------------------------------------
   

4. Now, navigate to the myConfluenceMacro directory that was created by the Atlassian Plugin SDK in the last step. 

5. Update the organization details for your plugin in the pom.xml file (see modify the plugin - step 1 from the Set up the Atlassian Plugin SDK and Build a Project tutorial if you're stuck).

6. Start up confluence with your plugin installed (and download all the necessary files to do that) by running the command atlas-run.

7. Check that Confluence started up with your plugin installed by navigating to localhost:1990/confluence/plugins/servlet/upm/manage/all (you can login using username: admin, password: admin just like you did in the last tutorial).

8. Leave Confluence up and running now

Create a Macro Element in Confluence

In the previous tutorial, we used the atlas-create-jira-plugin-module command to create a JIRA menu module which we then customised.  This command essentially modified the** /src/main/resources/atlassian-plugin.xml** file in your plugin directory to create some extra elements in JIRA.  

In this tutorial, you will create the plugin elements manually rather than using an SDK command.  This is because atlas-create-confluence-plugin-module command doesn't have an option for the Module type you need to use.

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

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

   1
   2
   <xhtml-macro name="helloworld" class="com.atlassian.tutorial.macro.helloworld" key='helloworld-macro'>
       <description key="helloworld.macro.desc"/>
       <category name="formatting"/>
       <parameters/>
   </xhtml-macro>
   

   save the changes to your file.  Note: your macro name and macro key should both be lower case. 

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

   1
   2
   helloworld.macro.desc="Hello World"
   

   save the changes to you file. 

4. Next you need to create the java class that you made reference to in Step 2. Because you'll be creating a couple of macros in this tutorial, you can create a **macro **folder to keep things tidy.

5. Open a new terminal window so you can create a new folder in the **/src/main/java/com/atlassian/tutorial **directory called macro:

   1
   2
   cd /src/main/java/com/atlassian/tutorial
   mkdir macro
   cd macro
   

6. In the folder, create a file called helloworld.java and open it in your favourite editor.

7. Enter the following code into helloworld.java:

   1
   2
   package com.atlassian.tutorial.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 helloworld 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.  

8. In your terminal window, change directory back to the top directory for your plugin (eg cd <home>/AtlassianTutorial/myConfluenceMacro)

9. Run the command atlas-mvn package to re-package your add-on and reinstall it using QuickReload. You should see a confirmation message:

   1
   2
   [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] ------------------------------------------------------------------------
   

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

    1
    2
    [INFO] [talledLocalContainer] 2016-10-10 18:33:16,082 INFO [QuickReload - Plugin Installer] [atlassian.plugin.manager.DefaultPluginManager] updatePlugin Updating plugin 'com.atlassian.tutorial.myConfluenceMacro-tests' from version '1.0.0-SNAPSHOT' to version '1.0.0-SNAPSHOT'
    [INFO] [talledLocalContainer] 2016-10-10 18:33:16,083 INFO [QuickReload - Plugin Installer] [atlassian.plugin.manager.DefaultPluginManager] broadcastPluginDisabling Disabling com.atlassian.tutorial.myConfluenceMacro-tests
    [INFO] [talledLocalContainer] 2016-10-10 18:33:17,512 INFO [QuickReload - Plugin Installer] [plugins.quickreload.install.PluginInstallerMechanic] installPluginImmediately
    [INFO] [talledLocalContainer]                       ^
    [INFO] [talledLocalContainer]                       |
    [INFO] [talledLocalContainer]                       |
    [INFO] [talledLocalContainer]                       |
    [INFO] [talledLocalContainer]                       |
    [INFO] [talledLocalContainer]                       |
    [INFO] [talledLocalContainer]
    [INFO] [talledLocalContainer]       A watched plugin never boils!
    [INFO] [talledLocalContainer]
    [INFO] [talledLocalContainer] Quick Reload Finished (5954 ms) - 'myConfluenceMacro-1.0.0-SNAPSHOT-tests.jar'
    

11. 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).

Customize the Hello World macro

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

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

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

3. Replace the <parameters/> element with the following:

   1
   2
   <parameters>
       <parameter name="Name" 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

4. Save and close the changes you made to atlassian-plugin.xml

5. Open **helloworld.java **(it'll be in the /src/main/java/com/atlassian/tutorial/macro directory)

6. Modify the **execute **function as follows:

   1
   2
   public String execute(Map<String, String> map, String s, ConversionContext conversionContext) throws MacroExecutionException {
       if (map.get("Name") != null) {
           return ("<h1>Hello " + map.get("Name") + "!</h1>");
       } else {
           return "<h1>Hello World!<h1>";
       }
   }
   

7. Save your changes to helloworld.java

8. In your terminal window, make sure you're in the top directory for your project (eg <home>/AtlassianTutorial/myConfluenceMacro) and run the command:

   1
   2
   atlas-mvn package
   

9. Monitor the terminal window where Confluence is running to confirm that the plugin has been reloaded by QuickReload.  

10. Log in and check your changes are working:

    

Format the macro appearance using css

At the moment, all the formatting work is being done in the **execute **function. In this section you'll set up a Web Resource Plugin Module to allow css to control the appearance of your macro.  

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

2. Notice that the <web-resource> parameter already exists:

   1
   2
   <web-resource key="myConfluenceMacro-resources" name="myConfluenceMacro Web Resources">
       <dependency>com.atlassian.auiplugin:ajs</dependency>
   
       <resource type="download" name="myConfluenceMacro.css" location="/css/myConfluenceMacro.css"/>
       <resource type="download" name="myConfluenceMacro.js" location="/js/myConfluenceMacro.js"/>
       <resource type="download" name="images/" location="/images"/>
   
       <context>myConfluenceMacro</context>
   </web-resource>
   

   In this tutorial you don't need to make any changes to the web-resource module itself. 

3. Below your <parameter name="Name" type="string" />, add a new <parameter name="Color" type="enum"> as follows:

   1
   2
   <parameter name="Color" type="enum">
       <value name="red"/>
       <value name="green"/>
       <value name="blue"/>
   </parameter>
   

   This will create a drop down menu in the macro editor for the user to select their color as either red, green or blue. 

4. Save your changes to atlassian-plugin.xml and close the file.

5. Next, open the src/main/resources/css/myConfluenceMacro.css file

6. Add the following css to the file:

   1
   2
   .blue h1 {
       color: blue;
   }
   
   .red h1 {
       color: red;
   }
   
   .green h1 {
       color: green;
   }
   

    This css will change the text colour for a .blue, .green and .red h1 element (once you've updated your helloworld.java of course).

7. Save your changes to myConfluenceMacro.css and close the file. 

8. Now, open the src/main/java/com/atlassian/tutorial/macro/helloworld.java file. 

9. Modify the **execute **function to create <div> elements as follows:

   1
   2
   public String execute(Map<String, String> map, String s, ConversionContext conversionContext) throws MacroExecutionException {
       String output = "<div class =\"helloworld\">";
       output = output + "<div class = \"" + map.get("Color") + "\">";
       if (map.get("Name") != null) {
           output = output + ("<h1>Hello " + map.get("Name") + "!</h1>");
       } else {
           output = output + "<h1>Hello World!<h1>";
       }
       output = output + "</div>" + "</div>";
       return output;
   }
   

   Notice that you are now creating a <div .../> element with a class matching the users nominated color.

10. Next, under the existing imports in your java file, add the following new lines:

    1
    2
    import com.atlassian.plugin.spring.scanner.annotation.component.Scanned;
    import com.atlassian.plugin.spring.scanner.annotation.imports.ComponentImport;
    import com.atlassian.webresource.api.assembler.PageBuilderService;
    import org.springframework.beans.factory.annotation.Autowired;
    

    These are required so you can use spring scanner, along with the PageBuilderService to ensure the css you've created is being included in Confluence.  

11. Above the public class helloworld implements Macro definition, add the following Spring annotations:

    1
    2
    @Scanned
    

    The @Scanned annotation is an instruction for spring scanner.  In this tutorial we used spring scanner 1.2.13 - so we needed to tell spring scanner to scan this class. 

12. Now, within the helloworld class definition, add a PageBuilderService variable, as well as a constructor for your helloworld class as follows:

    1
    2
    public class helloworld implements Macro {
    
        private PageBuilderService pageBuilderService;
    
        @Autowired
        public helloworld(@ComponentImport PageBuilderService pageBuilderService) {
            this.pageBuilderService = pageBuilderService;
        }
    

    The pageBuilderService is required for the Web Resource Plugin Module  

13. Finally, add the following line to your execute function:

    1
    2
    pageBuilderService.assembler().resources().requireWebResource("com.atlassian.tutorial.myConfluenceMacro:myConfluenceMacro-resources");
    

    Notice that you're using the pageBuilderService to require the web-resource key that was generated automatically (see step 2).

14. Save your changes and run atlas-mvn package to update your plugin.  

15. Make sure your plugin is working with the new changes:

Need Help?

The source code for this tutorial is available on Bitbucket  

Or, check out the questions on Atlassian Answers or create a request in our Developer Technical Support Portal.

Resources

• The source code for this tutorial is available on Bitbucket  
• You can find documentation for Spring Scanner at bitbucket.org/atlassian/atlassian-spring-scanner
• Learn more about the Web Resource Plugin Module
• Learn more about the Macro Module