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.
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 |
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 | Defines the tree structure of the space blueprint. |
If you need to add any additional pages, insert the |
| content-template | Defines the XML resource of a template in the storage format. |
|
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.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.
- Navigate to the template/page you wish to include in the space blueprint.
- Perform necessary amendments and changes to your template/page directly on the Confluence editor.
- 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.
- A new window should pop up, and any contents within are the storage format of the template/page.
- 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.
- 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.
- Launch your terminal (Linux/Mac) and change the directory to the root folder (“spaceblueprint“) with the following command.
cd ~/spaceblueprint - Package the source code into an installable add-on with the following command.
atlas-package - Step 2 will create both
.jaror.obradd-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] ------------------------------------------------------------------------ - Install the add-on via Manage add-ons page and hit the Upload add-on button on your Confluence test instance. Select either the
.jaror.obradd-on file from the “~/spaceblueprint/target” folder.
- 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!
