Writing Confluence Plugins

Confluence plugins provide a standard mechanism for extending Confluence. By adding plugins to Confluence you will be able to customise the site's look and feel, add new macros, event listeners, periodic tasks, and even introduce whole new features.

You can read Confluence Plugin Guide for an overview of what plugins are. This document introduces Confluence plugins to the developer who may want to write their own.

While Confluence plugins use the same plugin management code as JIRA 3.0 plugins, it's very unlikely that a JIRA plugin will work in Confluence or vice versa.

Anatomy of a Plugin

A plugin is a single jar file that can be dropped into Confluence's classpath. It consists of

• A plugin descriptor
• (Optional) Java classes
• (Optional) Resources

Plugins are composed of a series of modules, each of which defines a point at which the plugin interfaces with Confluence.

The basics: Creating a macro plugin skeleton

While even the most basic plugin involves quite a few directories and config files, creating a plugin skeleton is pretty easy and straightforward: We have prepared a Maven 2 template which does almost all the work for you! Please refer to the documentation in the Atlassian Developer Network​ for the general set-up phase. That documentation will tell you how to create the most basic Confluence macro plugin. You can use its basic code skeleton to evolve your plugin into one of the following categories.

Confluence Plugin Module Types

There are plenty of plugin types in Confluence. If you are new to plugin development in Confluence, we strongly suggest you start writing a simple Macro Plugin first. Macros are easy to write, give you visual feedback at once, and since the default plugin created by the Maven 2 template is a macro too you can virtually get started in almost no time at all.

Once you know your way around in the Confluence API, you can evolve your plugin into something else (or of course create a new plugin and start over from scratch). Each of the following plugin type descriptions assumes you have been able to create the most basic plugin skeleton mentioned in the above paragraph.

The Plugin Descriptor

The Plugin descriptor is an XML file that tells Confluence all about the plugin, and the modules contained within it. The descriptor must be a single file named atlassian-plugin.xml and must be located at the root of the jar file. Here's a sample plugin descriptor:

<!-- Every plugin must have a key, which identifies the plugin uniquely to the system -->
<!-- and a name, which is used to display the plugin in menus. -->
<atlassian-plugin key="com.atlassian.confluence.plugins.example"
name="Example Plugin">

<!-- The plugin info block allows you to provide more information about your plugin -->
<plugin-info>
<description>
A sample plugin for demonstrating the file format.
</description>
<version>1.0</version>
<!-- the versions of the application this plugin is for (both min and max are mandatory) -->
<application-version min="1.3" max="1.3"/>
<vendor name="Atlassian Software Systems Pty Ltd" url="http://www.atlassian.com/"/>
</plugin-info>

<!-- Here is where you define your modules. The code you use        -->
<!-- to define a module depends on the module itself. This is just  -->
<!-- a sample, which will not load if installed into Confluence     -->

<!-- Modules must have a key that is unique within the plugin, a name -->
<!-- and an implementing class. -->
<example key="module1" name="Example Module"
class="com.atlassian.confluence.plugins.example.ExampleModule">
<!-- All modules can optionally have a description -->
<description>An example module</description>
</example>
</atlassian-plugin>

Each plugin has a plugin key which must be unique to the plugin. We suggest using the Java convention of reversing your domain name in order to ensure your key is unique. Each module has a module key which need only be unique within the plugin it is defined.

 
Sometimes you will need to uniquely identify a module - you do this with the module complete key. A module with key fred in a plugin keyed as com.example.modules will have a complete key of com.example.modules:fred

All plugin modules have a class attribute, which tells the plugin manager which Java class it should instantiate when loading the module. What class you should provide depends on the module type. For example, theme, layout and colour-scheme modules can use classes already provided in Confluence (so you can write a theme pack without any Java code), but for macro and listener modules you need to write your own implementing class and include it in your plugin.

Java Classes

Because the plugin is a JAR that is dropped into the Confluence classpath, all Java classes contained within the JAR become a part of the Confluence application. You can include as many classes as you like, and have them interact with each other. Obviously, it's important to follow the Java package naming conventions to ensure your plugin's classes do not conflict with Confluence classes, or other plugins.

If you are writing a Java implementation of a plugin module (see the description of the module's class attribute above), you will be interested in Accessing Confluence Components From Plugin Modules.

You might also want to see the Confluence Developer FAQ, which answers particular questions that have come up from users regarding coding within Confluence.

Plugin and Module Resources

Resources are non-Java files that a plugin may need in order to operate. Examples of possible resources might be:

• A velocity file used to generate HTML for a macro or layout plugin module
• A CSS file required by a theme layout plugin module
• An image referenced from within a layout plugin module
• A macro help file
• A localisation property file

Resource definitions look like this. They can be either a part of the plugin, or part of a particular plugin module:

<!-- A resource has a type, a name and a location. The resource definition maps -->
<!-- some arbitrary resource name to where that resource would be located in    -->
<!-- the server's classpath -->
<resource type="velocity" name="template" location="com/example/plugin/template.vm"/>

<!-- For the localisation property file below, it must be named exampleplugin.properties -->
<!-- located under the resources folder -->
<resource type="i18n" name="i18n" location="resources/exampleplugin" />

<!-- Resources may contain arbitrary key/value pairs -->
<resource type="download" name="style.css" location="com/example/plugin/style.css">
   <property key="content-type" value="text/css"/>
</resource>

The name of the resource defines how the plugin module can locate a particular resource. The type of a resource tells the module how that resource can be used. A module can look for resources of a certain type or name: for example the layout plugin required that its help file is a file of type velocity and name help.

The location of a resource tells the plugin where the resource can be found in the jar file (resources are loaded by Java's classpath resource-loader). The full path to the file - without a leading slash - is required.

The simplest kind of resource, supported with all plugin module types, is of type download, which makes a resource available for download from the Confluence server at a particular URL. See: Adding Plugin and Module Resources.

Plugin Self-Configuration

Refer to the XML examples in the Atlassian Developer Network​.

The configuration URL is a link to a separate page, generally a new xwork action that you have defined. The WebDAV plugin is a good example of a plugin with a configuration screen. That configuration screen is available both from the Plugin Manager and from a web-item in the Administration menu.