The atlassian-plugin.xml Plugin Descriptor

The Plugin descriptor is an XML file that tells the application 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 pugin's 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>
    <!-- This version is displayed in the application's Plugin Manager. -->
    <version>1.0</version>
    <!-- The versions of the application this plugin is is compatible with -->
    <application-version min="1.3" max="1.3"/>
    <vendor name="Atlassian Software Systems Pty Ltd" url="http://www.atlassian.com/"/>
    <!-- The location of any plugin configuration (optional) -->
    <param name="configure.url">/admin/plugins/example/configurePlugin.action</param>
  </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.

The plugin key has to be defined in lower-case in the plugin descriptor. When you call the plugin in wiki markup you can use any capitilization (eg. {module1} or {Module1})

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, Confluence theme, layout and colour-scheme modules can use classes already provided in Confluence (so you can write a theme-plugin 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 application's classpath, all Java classes contained within the JAR become a part of the 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 the application's classes, or other plugins'.

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 application at a particular URL. See: Downloadable Plugin Resources.

Modules can be disabled by default by specifying state="disabled". Similarly, the entire plugin can by disabled by default with <atlassian-plugin state="disabled"/>

Plugin Configuration

Plugins can specify internal links within the application 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.

• Configuration links will most often point to XWork plugin modules within the plugin itself.
• Configuration links can be provided for a whole plugin and/or for any module within a plugin.
• Configuration links are relative to the application.

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: