Confluence 5 Tips: How to Develop Confluence Blueprints Addons

Recently released Conflunece 5 is no doubt a great product. New space sidebar, new Application navigator, new look and feel – at StiltSoft, we like all these features a lot. But most of all we like Confluence Blueprints that make creation of new content easy and quick.

Last week we rolled out a new version of Evernote Plugin that allows to create Confluence pages right from notes in Evernote. And Blueprints make this even easier.

Being one of the first developers employing Blueprints when creating plugins, we’d like to share our experience with others. To do that, we developed a nifty plugin that creates pages from good old wiki markup in the View mode. Confluence Blueprints allows to create pages without entering the Edit mode!

Step 1 – Creating the Plugin Project

To create the plugin project you can issue the atlas-create-confluence-plugin command from the Atlassian SDK and enter the following parameters:

group-id

com.stiltsoft.confluence.plugins

artifact-id

wiki-markup-blueprint-plugin

version

1.0.0-SNAPSHOT

package

com.stiltsoft.confluence.plugins.blueprint.markup

Step 2 – Add Plugin metadata to the POM

Now you can open the project in your favorite IDE and edit the metadata in the POM file. Let’s use the first milestone Confluence 5.1 in this example.

When developing Confluence Blueprints plugins, the blueprint module is a great help for developers. It has the following parameters:

the key attribute is the module key in the descriptor

the create-result attribute defines the behavior expected upon creation of new content with the help of Blueprints. The possible values are: edit (after completion of all steps, we’ll be taken to the Editor mode), view(after creating a page, we’ll be taken to the View mode, the page is created automatically)

the content-template-key attribute refers to the module key content-template declared later in atlassian-plugin.xml

the index-key attribute defines the index assigned to the created page (it’s worth mentioning that the index mechanism is quite powerful but is out of scope of this tutorial).

The dialog-wizard parameter of the blueprint module defines the dynamic behavior of what a user sees when creating content with the help of your Blueprint plugin. The parameter has the following attributes:

the id attribute is used when formatting html content as a part of a css class in the current window viewed by a user (for example, you can pile some css styles by defining the id attribute).

the template-key attribute defined the name of a soy function for windows content dynamic generation.

the title-key attribute is the key for a window title displayed to a user in the resource file.

The soy function we use is defined later in the web-resource module. Below is what the templates.soy file contains:

the key attribute is the module key in the descriptor (used in the blueprint module).

the resource tag defines the template used for creating of a new page.

the context-provider tag is the optional parameter that can be used for creating a page with additional variables.

Please note that the page template created from an xml file can contain dynamic variables taken from the context. In the plugin under consideration, the template looks like as follows:

<at:var at:name="wikiInXhtml" at:rawXhtml='true'/>

The variable that can be used in the template can be taken from the form filled by a user or added directly by context-provider. In this example we use context-provide that converts the wiki markup entered by a user in the enter box to the xhtml markup used in Confluence. The context-provider code is shown below:

You can learn more about parameter values used in the web-resource module on the module documentation page.

Please note that you should set the dependency from the resources com.atlassian.confluence.plugins.confluence-create-content-plugin:resources. Besides, you should register your Blueprint plugin in wiki-markup.js as shown below:

Step 4 – Use the plugin to create pages from the wiki markup

You won’t believe it, but this is almost the end of the tutorial. If you did everething right, you can install the plugin and start using it.

Moreover, you can download the plugin source code or try and go through all the steps yourself. If you have any question about plugin development for Confluence, you can contact our technical support and we will help you out.