I’m teaching myself how the write plugins for Atlassian Confluence wikis, specifically, Blueprint plugins. A blueprint plugin adds a custom entry to the Create Page button of your Confluence wiki. You can hook up a custom wizard that lets the user populate some fields that you can access later when you generate the wiki page with your blueprint. In the simplest case, the wizard lets you fill in the page title and, say, some labels. An advanced blueprint and its wizard can have more complex decision points, and it creates a wiki page by populating a custom template.
Getting Started With Blueprint Plugin Development
Atlassian provides a setup tutorial for beginners. Since it left some of my specific questions unanswered, I wrote my own tutorial how to get started with the Atlassian SDK in a previous blog entry. You should read it first.
After installing the Atlassian SDK, I continued going through the Simple Confluence Blueprint Creation tutorial.
Tip: Where the Simple Blueprint tutorial says “time to set up your IDE”, you can either continue with Eclipse as described, or figure it out in IntelliJ IDEA, or have a look at my Confluence Plugin Development with NetBeans tips.
How to Create a Blueprint Plugin:
Confluence projects are Maven-based, but the Atlassian SDK brings its own (useful!) Maven wrappers for project creation, running, testing, and cleaning.
- You create a skeleton project for a Confluence plugin using the atlas-create-confluence-plugin command provided by the Confluence SDK. You provide some properties, such as artifactId which is used as project name (in this example, kbarticle).
atlas-create-confluence-plugin Confirm properties configuration: groupId: com.my.company artifactId: kbarticle version: 1.0-SNAPSHOT (default) package: com.my.company (default)
You now have a directory named after your $artifactID, here: kbarticle.
Each Confluence plugin is made up of Plugin Modules. Go into the newly created plugin directory named after your $artifactId, and create a module:
cd kbarticle atlas-create-confluence-plugin-module
- Now specify module properties interactively. E.g. I chose to create a Blueprint plugin here.
Select Plugin Module: Blueprint (1)
- Define a reader-friendly blueprint name, description, index key, and one template key (I used the default template key).
Note: By index key, Confluence means the default label for all pages created from this Blueprint! So choose something user-friendly.
- I chose to add advanced features to my plugin, they are well described by the wizard. You need these features if you want to run a wizard dialog before plugin creation (dialog-wizard.js), or if you want a context object to access custom variables and provide dynamic text (ContentTemplateContextProvider.java), or if you want to run custom Java code after page creation (BlueprintCreatedListener.java), or if you want to generate special index pages, etc.
Congrats, you have created a skeleton plugin project.
How to Clean, Build, and Run Your Plugin
Next you want to clean, build, and package the skeleton plugin, and install it into a Confluence instance, and test it. The Atlassian SDK (
C:\Users\YOURHOME\atlassian-plugin-sdk\bin) provides you with the following development commands. You run these commands in your plugin directory, where the POM.xml file is.
atlas-clean — This command simply removes the generated ‘target’ directory so you can start a fresh build. I clean the project after I changed the POM or if I assume that changes to non-Java files were not picked up when I rebuilt the plugin (which happens and is quite annoying).
atlas-package — This command builds your plugin JAR in the ‘target’ directory. If you have installed a confluence instance, uninstall your old plugin, clear the browser cache, and reinstall the newly built plugin to test it. This manual development cycle works, but it is time-consuming and error prone.
atlas-run — This approach is the best practice for beginners. The command rebuilds the JAR, builds and starts a Confluence instance (yes!), and installs your plugin in it. It takes a while to download dependencies, but it’s not much slower than installing and running your own instance.
When the Confluence server is ready, the command prints your server URL (localhost) and port to the terminal.
[INFO] confluence started successfully in 633s at http://localhost:1990/confluence [INFO] Type Ctrl-D to shutdown gracefully [INFO] Type Ctrl-C to exit [INFO] [talledLocalContainer] INFO: Server startup in 12345 ms
Open the given Confluence server URL and log on to your temporary wiki instance using default credentials (admin/admin). Use the menus in the top right to open Administration>Add-ons. If you don’t see your plugin, set the filter to list “all addons” and verify that yours is enabled. If your plugin is missing or disabled (grayed out), you must fix an error before it can be used! Search for your plugin name in the terminal output, and interpret the StackTraces to find the error.
How to Work Smart using DevTools
After your skeleton plugin works, you want to add features, and test them right away in the browser. Typically, you use atlas-run together with Atlassian’s FastDev. The FastDev Plugin detects shift-reload of wiki pages in your browser, and reloads the underlying plugin. FastDev (as well as your own plugin!) is automatically included when you run atlas-run in your plugin directory. When you use atlas-run, you need to install neither FastDev nor your own plugin manually.
Go back to the Confluence instance running in the browser. Did you note the developer tools in bottom left corner? (They are collapsed by default! Click to unhide them.) Enable the Dev Tools buttons to ‘Rebuild’ and ‘Live Reload’ your plugin.
- The first button only reloads the plugin if the last-edited date of a compilable file has changed (typically, that’s a Java file).
- The second button claims to be able to reload other files too, but it doesn’t always reload all of them…
- Changes to atlassian-plugin.xml and pom.xml are like open heart surgery, so don’t expect it to reload these. Clean and rebuild if you edited these.
Being able to reload Java, SOY, and JS files definitely comes in handy during the main phase of development, when you already have the POM and plugin descriptor files down. After a major change, I typically clear the browser cache and press F5 to be sure I’m really testing the latest code. If my changes are not picked up or it gets stuck, I quit the server and re-run everything…
There are some things that I recommend doing first (before you write actual code), such as filling in your name and supplying an icon for the plugin, and getting an overview of what to put where — feel free to continue reading my blog post about that.