Confluence : Writing Confluence Plugins
This page last changed on Mar 04, 2007 by jnolen.
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 PluginA plugin is a single jar file that can be dropped into Confluence's classpath. It consists of
Plugins are composed of a series of modules, each of which defines a point at which the plugin interfaces with Confluence. Confluence Plugin Module TypesThe following types of plugin modules are supported by Confluence
The Plugin DescriptorThe 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 --> <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.
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 ClassesBecause 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 ResourcesResources are non-Java files that a plugin may need in order to operate. Examples of possible resources might be:
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: Downloadable Plugin Resources. Plugin Self-Configuration
Plugins can specify internal links within Confluence to configure themselves. This is useful where your plugin requires any configuration or user specific settings to work. For example, the Google Maps plugin requires a Google API Key from Google (which needs to be configured on each server) before it will work properly.
Plugin configuration - to add a configuration link for the whole plugin, place a single param element with the name configure.url within the plugin-info element at the top of the plugin descriptor: <plugin-info> <description>A macro which displays Google maps within a Confluence page.</description> <vendor name="Atlassian Software Systems Pty Ltd" url="http://www.atlassian.com/"/> <version>0.1</version> <param name="configure.url">/admin/plugins/gmaps/configurePlugin.action</param> </plugin-info> Plugin module configuration - to add a configuration link for a single module, place the same param element with the name configure.url within the descriptor element for that module: <macro name="gmap" class="com.atlassian.confluence.ext.gmaps.GmapsMacro" key="gmap"> <description>The individual map macro.</description> <param name="configure.url">/admin/plugins/gmaps/configureMacro.action</param> </macro> Here is an image showing where the Configure links appear for both a plugin and an individual module: |
![]() |
Document generated by Confluence on Mar 22, 2007 21:00 |