Developing a Confluence add-on


Posted by
Sean YONG

August 31, 2016

The hurdle

According to the research firm IDC, there are more than 18.5 million software developers in the world as of 2016. You must be thinking that’s a lot of software developers. Nope –  it’s nothing, really, if you compare it with the total population of approximately 7.4 billion. It’s barely a percentage!

Now, let’s hop to the question: how hard is developing a Confluence add-on? Well, I can assure you that no intensive programming skills are required here. In this blog, we are going to show how you can develop a customised space blueprint for your Confluence with a no-brainer guide (promise!). All you need to do is download the source file here and modify the templates you need for the space you are going to create frequently.

keep_calm_and_change_the_text_download__70535.1415018692.1280.1280

Prerequisite

Every development has its own prerequisite, including developing a Confluence add-on. Don’t fret, it’s nothing laborious. All you need is an Atlassian Plugin SDK – basically a software development kit – installed on your machine (click this link for more information). Next, make sure you have the latest Java environment installed… and you’re good to go!

Requirements Checked
Atlassian plugin SDK
Java 8
Research
Fancy skills
Wit
Confluence test instance
This source code is developed based on the latest Confluence 5.10.2 API. You may download the spaceblueprint-1.0.0.jar file and install it onto your local Confluence 5.10.x instance right away.

Let’s get started

Without further ado, let’s go ahead and download the zip file here and kickstart your project. This simple space blueprint comes with three predefined page templates right out of the box: a space homepage, a file repository and meeting minutes.

 

Template Screenshot
Space homepage
File repository
Meeting minutes

What’s next?

In this project, you will be dealing mainly with three source files (shown in the table below) throughout the development phase.

 

No. Source File Description
1 /spaceblueprint/src/main/resources/atlassian-plugin.xml Definition of web item, blueprint, content template, web dialogs etc.
2 /spaceblueprint/src/main/resources/spaceblueprint.properties Name and descriptions of web item, blueprint, content template and web dialogues.
3  /spaceblueprint/src/main/resources/xml/<your-file>.xml  Storage format of the blueprint templates.

1. atlassian-plugin.xml

This is the skeleton file which defines the tree structure of a space blueprint. It comprises of three sections: web items, space blueprint and content template.

 

Section Description Example source code
web-item Defines the web item of the dialogue launched by clicking the global Create Space or Create (for page) button.

<!-- space blueprint item-->

<web-item key="example-space-blueprint-item" il8n-name-key="confluence.example.blueprint.name" section="system.create.space.dialog/content">

   <description key="confluence.example.blueprint.desc"/>

   <resource name="icon" type="download" location="images/spaceBlueprintIcon.png"/>

   <param name="blueprintKey" value="example-space-blueprint"/>

</web-item>

(info) Most of the time, you won’t need to modify this section. However, you will need to copy and paste this section (with changed parameters value, i.e. name and description) if you are looking into adding another customised template for this space blueprint.

space-blueprint Defines the tree structure of the space blueprint.

<!-- space blueprint -->

<space-blueprint key="example-space-blueprint" il8n-name-key="confluence.example.blueprints.name" category="blueprint">

   <content-template ref="example-space-blueprint-template">

      <content-template ref="example-file-repo-template"/>

      <content-template ref="example-meeting-minutes-template"/>

   </content-template>

</space-blueprint> 

(info) The <content-template> section defines the tree structure upon space creation by default as illustrated below:

  • Parent: space home page
  • Child: file repository
  • Child: meeting minutes

If you need to add any additional pages, insert the <content-template ref="your-new-example-template"/> right before the </content-template> end tag. Please make sure the “ref” parameter value matches the correct key (i.e. <content-template key="example-file-repo-template">) defined within the content-template section below.

content-template Defines the XML resource of a template in the storage format.

 <!-- example file repo template -->

<content-template key="example-file-repo-template" il8n-name-key="confluence.example.blueprint.file.repo.name">

   <description key="confluence.example.blueprint.file.repo.desc"/>

   <resource name="template" type="download" location="/xml/file-repo.xml"/>

   <context-provider class="com.valiantys.confluence.example.blueprint.api.TemplateContextProvider"/>

<content-template>

(info) In this section, you need to make sure the parameters value is distinct from another <content-template>. That said, the following parameters value have to be distinctive.

  • content-template key
  • content-template il8n-name-key
  • description key
  • resource location

2. spaceblueprint.properties

This file is pretty straightforward. It contains all the naming conventions of the properties defined in the atlassian-plugin.xml file, such as  confluence.example.blueprint.name and confluence.example.blueprint.file.repo.name. You may refer to the example below:

# Item
confluence.example.blueprint.name=Example Space Blueprint
confluence.example.blueprint.desc=Create a new space with a set of predefined templates
# Dialogue
confluence.example.blueprints.dialog.create.title=Create an example space
confluence.example.blueprints.dialog.create.heading=Example Space Blueprint
confluence.example.blueprints.dialog.create.description=This space blueprint comes with a set of predefined templates
# File Repository
confluence.example.blueprint.file.repo.name=File Repository
confluence.example.blueprint.file.repo.desc=This is the file repository template

Names and descriptions defined in the spaceblueprint.properties file will be displayed on the Confluence user interface.

3. <your-file>.xml

This are zero restrictions on the file name, as long it matches the content template’s reference location within the <content-template> of the atlassian-plugin.xml file. You may refer to the following table for more information:

Parameters File name
<resource name=”template” type=”download” location=”/xml/home-page.xml”/> home-page.xml
<resource name=”template” type=”download” location=”/xml/file-repo.xml”/> file-repo.xml

As we mentioned earlier, these XML files contain the predefined contents of a particular template in storage format. The storage format of a template or a Confluence page can be retrieved in two different ways: first is the View Storage Format (view only) option available under the page Tools‘ drop-down menu; another is with the help of Confluence Source Editor (view and editable only). You can refer to the following steps to modify the storage format of a template or a Confluence page.

  1. Navigate to the template/page you wish to include in the space blueprint.
  2. Perform necessary amendments and changes to your template/page directly on the Confluence editor.
  3. Once you have finalised and are satisfied with the changes made, click on the Confluence Source Editor or the < > button next to the help button ? top right-hand corner.
  4. A new window should pop up, and any contents within are the storage format of the template/page.
  5. Highlight (CTRL A or CMD A) the storage format, then copy and paste the contents into the respective XML file of your choice (<your-file>.xml) from the “~/spaceblueprint/src/main/resources/xml” directory with you preferred text editor.
  6. Save the XML file.

How do I package the space blueprint?

Once you have added your very own templates, you are ready to turn these source files into an installable .jar or .obr add-on file. By now, you should have the Atlassian Plugin SDK installed on your machine.

  1. Launch your terminal (Linux/Mac) and change the directory to the root folder (“spaceblueprint“) with the following command.
    cd ~/spaceblueprint
  2. Package the source code into an installable add-on with the following command.
    atlas-package
  3. Step 2 will create both .jar or .obr add-on file in the “~/spaceblueprint/target” folder if the build is successful.
    [INFO] ------------------------------------------------------------------------
    [INFO] BUILD SUCCESS
    [INFO] ------------------------------------------------------------------------
    [INFO] Total time: 11.522 s
    [INFO] Finished at: 2016-07-29T16:23:00+00:00
    [INFO] Final Memory: 35M/335M
    [INFO] ------------------------------------------------------------------------
  4. Install the add-on via Manage add-ons page and hit the Upload add-on button on your Confluence test instance. Select either the .jar or .obr add-on file from the “~/spaceblueprint/target” folder.
  5. You should be able to see a new blueprint item Example Space Blueprint from the Create Space menu upon successful add-on installation.

    And the Meeting Minutes Blueprint too (if you have not removed anything) from the Create menu •••.

Piece of cake? Go try it out yourself!

Download the source code now and develop your very own space blueprint! If you have any questions, please feel free to leave a comment here. You can also hit us up to develop a space blueprint specially customised for you, too!